openapi: 3.0.0
info:
  title: ShipEngine API
  version: 1.1.202604070904
  termsOfService: https://www.shipengine.com/terms-of-service/
  x-logo:
    url: https://shipengine.github.io/img/shipengine-logo-square.png
    backgroundColor: '#FFFFFF'
    altText: ShipEngine logo
  contact:
    name: ShipEngine Sales & Support
    email: sales@shipengine.com
    url: https://www.shipengine.com/contact/
    x-phone: 1-512-856-5379
  license:
    name: Proprietary
    url: https://www.shipengine.com/terms-of-service/
  description: >
    ShipEngine's easy-to-use REST API lets you manage all of your shipping needs
    without worrying about the complexities of different carrier APIs and
    protocols. We handle all the heavy lifting so you can focus on providing a
    first-class shipping experience for your customers at the best possible
    prices.


    Each of ShipEngine's features can be used by itself or in conjunction with
    each other to build powerful shipping functionality into your application or
    service.
paths:
  /v1/account/settings:
    summary: Account settings
    description: ShipEngine Account settings
    get:
      summary: List account settings
      description: List all account settings for the ShipEngine account
      tags:
        - account
      operationId: list_account_settings
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_account_settings_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/account/settings/images:
    summary: Account settings images
    description: ShipEngine Account images
    get:
      summary: List account images
      description: List all account images for the ShipEngine account
      tags:
        - account
      operationId: list_account_images
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/list_account_settings_images_response_body
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Create an account image
      description: Create an Account Image
      tags:
        - account
      operationId: create_account_image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_account_settings_image_request_body'
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_account_settings_images_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/account/settings/images/{label_image_id}:
    summary: Account settings images
    description: ShipEngine Account images
    get:
      summary: Get account image by ID
      description: Retrieve information for an account image.
      tags:
        - account
      operationId: get_account_settings_images_by_id
      parameters:
        - name: label_image_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/image_id'
          description: Label Image Id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_account_settings_images_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    put:
      summary: Update account image by ID
      description: Update information for an account image.
      tags:
        - account
      operationId: update_account_settings_images_by_id
      parameters:
        - name: label_image_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/image_id'
          description: Label Image Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_account_settings_image_request_body'
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    delete:
      summary: Delete account image by ID
      description: Delete Account Image By Id
      tags:
        - account
      operationId: delete_account_image_by_id
      parameters:
        - name: label_image_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/image_id'
          description: Label Image Id
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/addresses/recognize:
    summary: Parse an address
    description: >
      Data often enters your system as unstructured text (for example: emails,
      SMS messages, support tickets, or other documents). ShipEngine's
      address-recognition API helps you extract meaningful address data (e.g.
      recipient name, address line 1, line 2, city, postal code) from this
      unstructured text.
    put:
      summary: Parse an address
      description: >
        The address-recognition API makes it easy for you to extract address
        data from unstructured text, including the recipient name, line 1, line
        2, city, postal code, and more.


        Data often enters your system as unstructured text (for example: emails,
        SMS messages, support tickets, or other documents). ShipEngine's
        address-recognition API helps you extract meaningful, structured data
        from this unstructured text. The parsed address data is returned in the
        same structure that's used for other ShipEngine APIs, such as address
        validation, rate quotes, and shipping labels.


        > **Note:** Address recognition is currently supported for the United
        States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.
      tags:
        - addresses
      operationId: parse_address
      requestBody:
        required: true
        description: >
          The only required field is `text`, which is the text to be parsed. You
          can optionally also provide an `address` containing already-known
          values. For example, you may already know the recipient's name, city,
          and country, and only want to parse the street address into separate
          lines.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/parse_address_request_body'
            examples:
              text_only:
                summary: Text only
                description: >
                  This is the simplest way to call the address-recognition API.
                  Just pass the text to be parsed and nothing else.
                value:
                  text: >-
                    Margie McMiller at 3800 North Lamar suite 200 in austin,
                    tx.  The zip code there is 78652.
              some_known_fields:
                summary: Some known fields
                description: >
                  You can optionally provide an `address` object containing any
                  already-known values. For example, you may already know the
                  recipient's name, city, and country, and only want to parse
                  the street address into separate lines.
                value:
                  text: >-
                    Margie McMiller at 3800 North Lamar suite 200 in austin,
                    tx.  The zip code there is 78652.
                  address:
                    country_code: US
                    address_residential_indicator: 'yes'
      responses:
        '200':
          description: >
            Returns the parsed address, as well as a confidence score and a list
            of all the entities that were recognized in the text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/parse_address_response_body'
              examples:
                text_only:
                  description: >
                    This response shows that the address-recognition API was
                    able to recognize all the address entities in the text.
                    Notice that the `country_code` is not populated and the
                    `address_residential_indicator` is "unknown", since neither
                    of these fields was included in the text.
                  value:
                    score: 0.9122137426845613
                    address:
                      name: Margie McMiller
                      address_line1: 3800 North Lamar
                      address_line2: Suite 200
                      city_locality: Austin
                      state_province: TX
                      postal_code: '78652'
                      address_residential_indicator: unknown
                    entities:
                      - type: person
                        score: 0.9519646137063122
                        text: Margie McMiller
                        start_index: 0
                        end_index: 14
                        result:
                          value: Margie McMiller
                      - type: address_line
                        score: 0.9805313966503588
                        text: 3800 North Lamar
                        start_index: 19
                        end_index: 34
                        result:
                          line: 1
                          value: 3800 North Lamar
                      - type: number
                        score: 0.9805313966503588
                        text: '3800'
                        start_index: 19
                        end_index: 22
                        result:
                          type: cardinal
                          value: 3800
                      - type: address_line
                        score: 1
                        text: suite 200
                        start_index: 36
                        end_index: 44
                        result:
                          line: 2
                          value: Suite 200
                      - type: number
                        score: 0.9805313966503588
                        text: '200'
                        start_index: 42
                        end_index: 44
                        result:
                          type: cardinal
                          value: 200
                      - type: city_locality
                        score: 0.9805313966503588
                        text: austin
                        start_index: 49
                        end_index: 54
                        result:
                          value: Austin
                      - type: state_province
                        score: 0.6082904353940255
                        text: tx
                        start_index: 57
                        end_index: 58
                        result:
                          name: Texas
                          value: TX
                      - type: postal_code
                        score: 0.9519646137063122
                        text: '78652'
                        start_index: 84
                        end_index: 88
                        result:
                          value: 78652
                some_known_fields:
                  description: >
                    This response is shows that the address-recognition API was
                    able to recognize all the address entities in the text.
                    Notice that the `country_code` and
                    `address_residential_indicator` fields are populated with
                    the values that were provided in the request.
                  value:
                    score: 0.9122137426845613
                    address:
                      name: Margie McMiller
                      address_line1: 3800 North Lamar
                      address_line2: Suite 200
                      city_locality: Austin
                      state_province: TX
                      postal_code: '78652'
                      country_code: US
                      address_residential_indicator: 'yes'
                    entities:
                      - type: person
                        score: 0.9519646137063122
                        text: Margie McMiller
                        start_index: 0
                        end_index: 14
                        result:
                          value: Margie McMiller
                      - type: address_line
                        score: 0.9805313966503588
                        text: 3800 North Lamar
                        start_index: 19
                        end_index: 34
                        result:
                          line: 1
                          value: 3800 North Lamar
                      - type: number
                        score: 0.9805313966503588
                        text: '3800'
                        start_index: 19
                        end_index: 22
                        result:
                          type: cardinal
                          value: 3800
                      - type: address_line
                        score: 1
                        text: suite 200
                        start_index: 36
                        end_index: 44
                        result:
                          line: 2
                          value: Suite 200
                      - type: number
                        score: 0.9805313966503588
                        text: '200'
                        start_index: 42
                        end_index: 44
                        result:
                          type: cardinal
                          value: 200
                      - type: city_locality
                        score: 0.9805313966503588
                        text: austin
                        start_index: 49
                        end_index: 54
                        result:
                          value: Austin
                      - type: state_province
                        score: 0.6082904353940255
                        text: tx
                        start_index: 57
                        end_index: 58
                        result:
                          name: Texas
                          value: TX
                      - type: postal_code
                        score: 0.9519646137063122
                        text: '78652'
                        start_index: 84
                        end_index: 88
                        result:
                          value: 78652
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/addresses/validate:
    summary: Address validation
    description: >
      Address validation ensures accurate addresses and can lead to reduced
      shipping costs by preventing address correction surcharges.

      ShipEngine cross references multiple databases to validate addresses and
      identify potential deliverability issues.
    post:
      summary: Validate an address
      description: >
        Address validation ensures accurate addresses and can lead to reduced
        shipping costs by preventing address correction surcharges.

        ShipEngine cross references multiple databases to validate addresses and
        identify potential deliverability issues.
      tags:
        - addresses
      operationId: validate_address
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/validate_address_request_body'
            examples:
              all_known_fields_request:
                summary: All known fields
                description: A call that returns a status of `verified`.
                value:
                  - name: Mickey and Minnie Mouse
                    phone: 714-781-4565
                    company_name: The Walt Disney Company
                    address_line1: 500 South Buena Vista Street
                    city_locality: Burbank
                    state_province: CA
                    postal_code: '91521'
                    country_code: US
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validate_address_response_body'
              examples:
                all_known_fields:
                  summary: All known fields
                  description: A response for a `verified` status call.
                  value:
                    - status: verified
                      original_address:
                        name: Mickey and Minnie Mouse
                        phone: 714-781-4565
                        company_name: The Walt Disney Company
                        address_line1: 500 South Buena Vista Street
                        address_line2: null
                        address_line3: null
                        city_locality: Burbank
                        state_province: CA
                        postal_code: '91521'
                        country_code: US
                        address_residential_indicator: unknown
                      matched_address:
                        name: MICKEY AND MINNIE MOUSE
                        phone: 714-781-4565
                        company_name: THE WALT DISNEY COMPANY
                        address_line1: 500 S BUENA VISTA ST
                        address_line2: null
                        address_line3: null
                        city_locality: BURBANK
                        state_province: CA
                        postal_code: 91521-0007
                        country_code: US
                        address_residential_indicator: 'no'
                      messages: []
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/batches:
    summary: Batches
    description: >
      Batches are an advanced feature of ShipEngine designed for users who need
      to generate hundreds or thousands of labels at a time.

      When ShipEngine generates labels it relies on many carriers, their
      services, their dependencies, and a number of other variables

      to fulfill your requests; those requests can take a few minutes for us to
      get back to you.
    get:
      summary: List batches
      description: List Batches associated with your Shipengine account
      operationId: list_batches
      tags:
        - batches
      parameters:
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/batch_status'
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          example: 2
          description: >
            Return a specific page of results. Defaults to the first page. If
            set to a number that's greater than the number of pages of results,
            an empty page is returned.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 25
          example: 50
          description: The number of results to return per response.
        - name: sort_dir
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/sort_dir'
            default: desc
          description: Controls the sort order of the query.
        - name: batch_number
          in: query
          required: false
          schema:
            type: string
          description: Batch Number
        - description: >-
            Only return batches that were created on or after a specific
            date/time
          name: created_at_start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
        - description: >-
            Only return batches that were created on or before a specific
            date/time
          name: created_at_end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
        - description: >-
            Only return batches that were processed on or after a specific
            date/time
          name: processed_at_start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
        - description: >-
            Only return batches that were processed on or before a specific
            date/time
          name: processed_at_end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
        - name: sort_by
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/batches_sort_by'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_batches_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Create a batch
      description: Create a Batch
      tags:
        - batches
      operationId: create_batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_batch_request'
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_batch_response_body'
        '207':
          description: >-
            The request was a partial success. It contains results, as well as
            processing errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_batch_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/batches/external_batch_id/{external_batch_id}:
    summary: External batch ID
    description: Retrive a batch from an external batch ID
    parameters:
      - name: external_batch_id
        in: path
        required: true
        schema:
          type: string
        example: 13553d7f-3c87-4771-bae1-c49bacef11cb
    get:
      summary: Get batch by external ID
      description: Get Batch By External ID
      tags:
        - batches
      operationId: get_batch_by_external_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_batch_by_external_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/batches/{batch_id}:
    summary: Batch by ID
    description: Check the status of your batch by retrieving it with a Batch ID.
    parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Batch ID
    delete:
      summary: Delete batch by ID
      description: Delete Batch By Id
      operationId: delete_batch
      tags:
        - batches
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    get:
      summary: Get batch by ID
      description: Get Batch By ID
      tags:
        - batches
      operationId: get_batch_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_batch_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    put:
      summary: Update batch by ID
      description: Update Batch By Id
      operationId: update_batch
      tags:
        - batches
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/batches/{batch_id}/add:
    summary: Add funds to a carrier
    description: >
      You can check your balance for a particular carrier by calling List
      Carriers endpoint.

      For any carrier account where requires_funded_amount is true, you can add
      funds.
    parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Batch ID
    post:
      summary: Add to a batch
      description: Add a Shipment or Rate to a Batch
      tags:
        - batches
      operationId: add_to_batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/add_to_batch_request_body'
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/batches/{batch_id}/errors:
    summary: Batch errors
    description: >
      Error handling in batches are handled differently than in a single
      synchronous request.

      You must retrieve the status of your batch by getting a batch and getting
      an overview of the statuses or you can list errors directly here below to
      get detailed information about the errors.
    parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Batch ID
    get:
      summary: Get batch errors
      description: >
        Error handling in batches are handled differently than in a single
        synchronous request.

        You must retrieve the status of your batch by getting a batch and
        getting an overview of the statuses or you can list errors directly here
        below to get detailed information about the errors.
      tags:
        - batches
      operationId: list_batch_errors
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          example: 2
          description: >
            Return a specific page of results. Defaults to the first page. If
            set to a number that's greater than the number of pages of results,
            an empty page is returned.
        - name: pagesize
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_batch_errors_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/batches/{batch_id}/process/labels:
    summary: Process batch ID labels
    description: Process Batch ID Labels
    parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Batch ID
    post:
      summary: Process batch ID labels
      description: Process Batch ID Labels
      tags:
        - batches
      operationId: process_batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/process_batch_request_body'
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/batches/{batch_id}/remove:
    summary: Remove batch by ID
    description: Remove a list of shipments from a batch
    parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Batch ID
    post:
      summary: Remove from batch
      description: Remove a shipment or rate from a batch
      tags:
        - batches
      operationId: remove_from_batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/remove_from_batch_request_body'
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/carriers:
    summary: Carriers
    description: >
      Carriers are a company or individual that specializes in transporting
      freight from one destination to another.

      Shipengine allows you to easily integrate with multiple carriers so you
      can chose the shipping option that is right for you.
    get:
      summary: List carriers
      description: List all carriers that have been added to this account
      tags:
        - carriers
      operationId: list_carriers
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          example: 2
          description: >
            Return a specific page of results. Defaults to the first page. If
            set to a number that's greater than the number of pages of results,
            an empty page is returned.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 25
          example: 50
          description: The number of results to return per response.
        - name: include_extended_details
          in: query
          required: false
          schema:
            type: boolean
            default: true
          example: false
          description: >
            When `true` (the default), each carrier in the response includes two
            additional arrays: `packages` (the package types supported by that
            carrier) and `options` (the carrier-level advanced options available
            for that carrier).

            Set to `false` to omit both arrays and reduce response payload size.
            This is useful when you only need basic carrier information such as
            `carrier_id`, `balance`, or `services`.
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_carriers_response_body'
        '207':
          description: >-
            The request was a partial success. It contains results, as well as
            errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_carriers_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/carriers/{carrier_id}:
    summary: Individual carriers
    description: >-
      Perform actions and get information on individual carriers connected with
      your account.
    parameters:
      - name: carrier_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        example: se-28529731
        description: Carrier ID
    get:
      summary: Get carrier by ID
      description: Retrive carrier info by ID
      tags:
        - carriers
      operationId: get_carrier_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_carrier_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    delete:
      summary: Disconnect carrier by ID
      description: Disconnect a Carrier of the given ID from the account
      tags:
        - carriers
      operationId: disconnect_carrier_by_id
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/carriers/{carrier_id}/add_funds:
    summary: Carrier funds
    description: >-
      All carriers require that funds to be attached to an account to ensure
      payment for the various services they provide to their customers.
    parameters:
      - name: carrier_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        example: se-28529731
        description: Carrier ID
    put:
      summary: Add funds to carrier
      description: Add Funds To A Carrier
      tags:
        - carriers
      operationId: add_funds_to_carrier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/add_funds_to_carrier_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/add_funds_to_carrier_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/carriers/{carrier_id}/options:
    summary: Carrier options
    description: >-
      Carriers support various options for particular shipments. Ex.
      (non-machinable, is_alcohol, fragile, etc)
    parameters:
      - name: carrier_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        example: se-28529731
        description: Carrier ID
    get:
      summary: Get carrier options
      description: Get a list of the options available for the carrier
      tags:
        - carriers
      operationId: get_carrier_options
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_carrier_options_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/carriers/{carrier_id}/packages:
    summary: Carrier packages
    description: >
      Carriers support many different package types, Shipengine supports
      retrieving all available package so that

      you can best determine what is right for your particular shipment.
    parameters:
      - name: carrier_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        example: se-28529731
        description: Carrier ID
    get:
      summary: List carrier package types
      description: >-
        List the package types associated with the carrier. This endpoint only
        returns carrier-provided package types, not custom package types.
      tags:
        - carriers
      operationId: list_carrier_package_types
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_carrier_package_types_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/carriers/{carrier_id}/services:
    summary: Carrier services
    description: >
      Carrier services usually refer to the various shipping options that a
      carrier provides to its customers.

      Ex. Priority mail, overnight, international
    parameters:
      - name: carrier_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        example: se-28529731
        description: Carrier ID
    get:
      summary: List carrier services
      description: List the services associated with the carrier ID
      tags:
        - carriers
      operationId: list_carrier_services
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_carrier_services_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/connections/carriers/{carrier_name}:
    summary: Carrier connections
    description: Carrier connections
    parameters:
      - name: carrier_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/carrier_name'
        example: dhl_express
        description: >-
          The carrier name, such as `stamps_com`, `ups`, `fedex`, or
          `dhl_express`.
    post:
      summary: Connect a carrier account
      description: Connect a carrier account
      tags:
        - carrier_accounts
      operationId: connect_carrier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/connect_carrier_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/connect_carrier_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/connections/carriers/{carrier_name}/{carrier_id}:
    summary: Disconnect a carrier
    description: Disconnect a carrier
    parameters:
      - name: carrier_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/carrier_name'
        example: dhl_express
        description: >-
          The carrier name, such as `stamps_com`, `ups`, `fedex`, or
          `dhl_express`.
      - name: carrier_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        example: se-28529731
        description: Carrier ID
    delete:
      summary: Disconnect a carrier
      description: Disconnect a carrier
      tags:
        - carrier_accounts
      operationId: disconnect_carrier
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/connections/carriers/{carrier_name}/{carrier_id}/settings:
    summary: Carrier settings
    description: Carrier settings
    parameters:
      - name: carrier_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/carrier_name_with_settings'
        example: dhl_express
        description: The carrier name, such as `ups`, `fedex`, or `dhl_express`.
      - name: carrier_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        example: se-28529731
        description: Carrier ID
    get:
      summary: Get carrier settings
      description: Get carrier settings
      tags:
        - carrier_accounts
      operationId: get_carrier_settings
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_carrier_settings_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    put:
      summary: Update carrier settings
      description: Update carrier settings
      tags:
        - carrier_accounts
      operationId: update_carrier_settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_carrier_settings_request_body'
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/connections/insurance/shipsurance:
    summary: Shipsurance connection
    description: Shipsurance Connection
    delete:
      summary: Disconnect a shipsurance account
      description: Disconnect a Shipsurance Account
      deprecated: true
      operationId: disconnect_insurer
      tags:
        - insurance
      responses:
        '200':
          description: The request was a success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/disconnect_insurer_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Connect a shipsurance account
      description: Connect a Shipsurance Account
      deprecated: true
      operationId: connect_insurer
      tags:
        - insurance
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/connect_insurer_request_body'
        required: true
      responses:
        '200':
          description: The request was a success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/connect_insurer_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/documents/combined_labels:
    summary: Created combined label document
    description: Download a combined label file
    post:
      summary: Created combined label document
      description: Download a combined label file
      tags:
        - labels
      operationId: create_combined_label_document
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_combined_label_document_request_body'
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/create_combined_label_document_response_body.yaml
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/downloads/{dir}/{subdir}/{filename}:
    summary: File download
    description: >
      This endpoint is used to download forms that are generated in the various
      pdf, png, zpl formats

      such as labels and batches
    parameters:
      - name: subdir
        in: path
        required: true
        schema:
          type: string
      - name: filename
        in: path
        required: true
        schema:
          type: string
      - name: dir
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Download file
      description: Get File
      operationId: download_file
      tags:
        - downloads
      parameters:
        - name: download
          in: query
          required: false
          schema:
            type: string
        - name: rotation
          in: query
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: The request was a success
          content:
            application/pdf:
              schema:
                $ref: '#/components/schemas/download_file_pdf_response_body'
            image/png:
              schema:
                $ref: '#/components/schemas/download_file_png_response_body'
            application/zpl:
              schema:
                $ref: '#/components/schemas/download_file_zpl_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/environment/webhooks:
    summary: Webhooks
    description: >
      ShipEngine exposes asynchronous operations for long running operations
      such as batch labels and rates.

      Webhooks allow the ShipEngine servers to contact your servers when an
      operation changes state, such as a batch label creation completion.
    get:
      summary: List webhooks
      description: List all webhooks currently enabled for the account.
      tags:
        - webhooks
      operationId: list_webhooks
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_webhooks_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Create a webhook
      description: Create a webhook for specific events in the environment.
      tags:
        - webhooks
      operationId: create_webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_webhook_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_webhook_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '409':
          $ref: '#/components/responses/409_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/environment/webhooks/{webhook_id}:
    summary: Webhook
    description: Retrieve, update, and delete information for individual webhooks
    parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Webhook ID
    get:
      summary: Get webhook by ID
      description: Retrieve individual webhook by an ID
      tags:
        - webhooks
      operationId: get_webhook_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_webhook_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    put:
      summary: Update a webhook
      description: Update the webhook url property
      tags:
        - webhooks
      operationId: update_webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_webhook_request_body'
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    delete:
      summary: Delete webhook by ID
      description: Delete a webhook
      tags:
        - webhooks
      operationId: delete_webhook
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/freight/provider_accounts:
    summary: Freight provider accounts
    description: |
      List the freight provider accounts connected to your account.
    get:
      summary: List freight provider accounts
      description: >
        Return the freight provider accounts connected to your account. Every
        freight request identifies the account it goes through with a
        `freight_provider_account_id`, so start here to find the ID to quote,
        book, and track with.


        Only active connections are returned. An account with no freight
        provider connected receives an empty array.
      operationId: list_freight_provider_accounts
      tags:
        - freight
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/list_freight_provider_accounts_response_body
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/freight/quotes:
    summary: Freight quotes
    description: >
      Request less-than-truckload (LTL) freight rates from the carriers
      available through a freight provider connected to your account.
    post:
      summary: Get freight quotes
      description: >
        Retrieve freight rate offers for a shipment. Each offer in the response
        is a bookable quote from a specific LTL carrier.


        There are two ways to request quotes:


        - **Inline.** Describe the shipment in the request: `ship_from`,
        `ship_to`, and `handling_units`.

        - **Linked to an existing shipment.** Provide `shipment_id`. The origin
        is taken from the shipment's ship-from warehouse and the destination
        from the order's ship-to address, so `ship_from` and `ship_to` must be
        omitted. `handling_units`, `accessorials`, and `insurance` are optional
        in this mode: when provided they are saved as the shipment's freight
        configuration, and when omitted the previously saved configuration is
        reused.


        To book one of the returned offers, pass its `offer_id` to [Book a
        freight shipment](#operation/book_freight_shipment).


        All dimensions are interpreted as inches and all weights as pounds.
      operationId: get_freight_quotes
      tags:
        - freight
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/get_freight_quotes_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/freight_quotes_response_body'
        '400':
          description: >
            The request contained errors, the freight provider connection is not
            active for the account, or the provider could not return quotes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
              example:
                request_id: 4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a
                errors:
                  - error_source: shipengine
                    error_type: business_rules
                    error_code: unspecified
                    message: >-
                      ship_from and ship_to must not be provided when
                      shipment_id is present
        '404':
          description: The `shipment_id` does not identify a shipment on this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/freight/shipments:
    summary: Freight shipments
    description: >
      Book freight offers returned by [Get freight
      quotes](#operation/get_freight_quotes) and list the freight shipments on
      your account.
    post:
      summary: Book a freight shipment
      description: >
        Book one of the offers returned by [Get freight
        quotes](#operation/get_freight_quotes). Booking dispatches the shipment
        with the LTL carrier and generates the shipment's documents, such as the
        Bill of Lading.


        As with quoting, there are two ways to book:


        - **Linked to an existing shipment.** Provide `shipment_id`. The
        shipment must already have a freight quote — call [Get freight
        quotes](#operation/get_freight_quotes) for it first. The origin,
        destination, and handling units all come from the shipment and its saved
        freight configuration, so `ship_from`, `ship_to`, and `handling_units`
        must be omitted.

        - **Inline.** Omit `shipment_id` and provide `ship_from`, `ship_to`, and
        `handling_units`. A shipment record is created for the booking and
        marked as shipped.


        Pass the `offer_id` from the offer you are booking. The provider
        connection, carrier, and expiration are resolved server-side from the
        stored offer.
      operationId: book_freight_shipment
      tags:
        - freight
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/book_freight_shipment_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/book_freight_shipment_response_body'
        '400':
          description: >
            The request contained errors, the quote has expired, the freight
            provider connection is not active for the account, the linked
            shipment has no freight configuration or a cancelled one, or the
            provider rejected the booking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
              example:
                request_id: 4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a
                errors:
                  - error_source: shipengine
                    error_type: system
                    error_code: unspecified
                    message: The quote has expired. Please request a new quote.
        '404':
          description: The `shipment_id` does not identify a shipment on this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
        '500':
          $ref: '#/components/responses/500_error_response'
    get:
      summary: List freight shipments
      description: >
        Return the freight shipments on your account, most recently created
        first. Results are paginated.
      operationId: list_freight_shipments
      tags:
        - freight
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          example: 1
          description: The page of results to return. Values below `1` are treated as `1`.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 500
            default: 25
          example: 50
          description: >-
            The number of freight shipments to return per page. Values above
            `500` are capped at `500`.
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_freight_shipments_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/freight/shipments/{freight_shipment_id}:
    summary: Freight shipment
    description: Retrieve or cancel an individual freight shipment.
    parameters:
      - name: freight_shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        example: se-98765432
        description: The identifier of the freight shipment.
    get:
      summary: Get freight shipment by ID
      description: >
        Retrieve a single freight shipment, including its current status,
        carrier reference numbers, and the documents generated for it.
      operationId: get_freight_shipment_by_id
      tags:
        - freight
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/freight_shipment_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          description: The freight shipment does not exist on this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
              example:
                request_id: 4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a
                errors:
                  - error_source: shipengine
                    error_type: business_rules
                    error_code: invalid_identifier
                    message: Invalid freight_shipment_id.
                    field_name: freight_shipment_id
        '500':
          $ref: '#/components/responses/500_error_response'
    delete:
      summary: Cancel a freight shipment
      description: >
        Cancel a booked freight shipment with the carrier. The response
        indicates whether the associated pickup was also cancelled.


        Cancellation windows are set by the carrier. A shipment that has already
        been picked up usually cannot be cancelled, and the provider's rejection
        is returned as a `400 Bad Request`.
      operationId: cancel_freight_shipment
      tags:
        - freight
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cancel_freight_shipment_response_body'
        '400':
          description: >-
            The freight shipment ID is malformed, or the provider rejected the
            cancellation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
        '404':
          description: The freight shipment does not exist on this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/freight/shipments/{freight_shipment_id}/documents:
    summary: Freight shipment documents
    description: List the documents generated for a freight shipment.
    parameters:
      - name: freight_shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        example: se-98765432
        description: The identifier of the freight shipment.
    get:
      summary: List freight shipment documents
      description: >
        List the documents available for a freight shipment, such as the Bill of
        Lading, pallet labels, and the proof of delivery. Documents become
        available as the shipment progresses: the Bill of Lading is generated at
        booking, while a proof of delivery only exists after delivery.


        Each document's `url` is a path on the API host that returns the PDF,
        for example `https://api.shipengine.com/v1/downloads/...`.
      operationId: list_freight_shipment_documents
      tags:
        - freight
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/list_freight_shipment_documents_response_body
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          description: The freight shipment does not exist on this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/freight/shipments/{freight_shipment_id}/tracking:
    summary: Freight shipment tracking
    description: Retrieve live tracking for a booked freight shipment.
    parameters:
      - name: freight_shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        example: se-98765432
        description: The identifier of the freight shipment.
    get:
      summary: Get freight shipment tracking
      description: >
        Retrieve the current tracking status and event history for a booked
        freight shipment directly from the carrier.


        The shipment is tracked by its PRO number when one has been assigned,
        and by its BOL number otherwise. A shipment that has neither returns a
        `400 Bad Request` with error code `freight_tracking_not_available` —
        this is normal immediately after booking, before the carrier assigns a
        PRO number.
      operationId: get_freight_shipment_tracking
      tags:
        - freight
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/freight_shipment_tracking_response_body'
        '400':
          description: >
            The freight shipment ID is malformed, the shipment has no PRO or BOL
            number to track yet (`freight_tracking_not_available`), or the
            freight provider connection is not active
            (`freight_connection_inactive`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
              example:
                request_id: 4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a
                errors:
                  - error_source: shipengine
                    error_type: business_rules
                    error_code: freight_tracking_not_available
                    message: >-
                      Tracking is not yet available for this shipment. A PRO or
                      BOL number is required.
        '404':
          description: >
            The freight shipment does not exist on this account
            (`freight_shipment_not_found`), or the carrier returned no tracking
            information (`freight_tracking_not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
              example:
                request_id: 4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a
                errors:
                  - error_source: carrier
                    error_type: business_rules
                    error_code: freight_tracking_not_found
                    message: No tracking information was found for this shipment.
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/freight/tracking:
    summary: Freight tracking by number
    description: Track any freight shipment by its PRO or BOL number.
    get:
      summary: Get freight tracking by number
      description: >
        Retrieve tracking for a freight shipment by its PRO or BOL number,
        whether or not the shipment was booked through ShipEngine. Use this when
        you have the carrier's reference number but no `freight_shipment_id` —
        for example, for a shipment booked outside the API.


        `carrier_scac` is required as well as the number itself, because the
        freight provider needs the SCAC to resolve a tracking number.
      operationId: get_freight_tracking
      tags:
        - freight
      parameters:
        - name: freight_provider_account_id
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/se_id'
          example: se-4821
          description: >
            The freight provider account to track through. Retrieve it with
            [List freight provider
            accounts](#operation/list_freight_provider_accounts).
        - name: tracking_number
          in: query
          required: true
          schema:
            type: string
            minLength: 1
          example: 072-51293847
          description: The PRO or BOL number to track.
        - name: tracking_type
          in: query
          required: true
          schema:
            type: string
            enum:
              - pro_number
              - bol_number
          example: pro_number
          description: Which kind of number `tracking_number` is.
        - name: carrier_scac
          in: query
          required: true
          schema:
            type: string
            minLength: 1
          example: FXFE
          description: >
            The Standard Carrier Alpha Code (SCAC) of the LTL carrier. Required:
            the freight provider needs the SCAC to resolve a tracking number.
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/freight_tracking_response_body'
        '400':
          description: >
            `freight_provider_account_id` is missing or is not a valid account
            ID (`freight_provider_id_required`), `tracking_number`,
            `tracking_type`, or `carrier_scac` is missing or invalid, or the
            freight provider connection is not active
            (`freight_connection_inactive`).


            The `freight_provider_id_required` message still names the parameter
            `seller_freight_provider_id`, the name this parameter had
            previously. Match on `error_code`, not on `message`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
              example:
                request_id: 4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a
                errors:
                  - error_source: shipengine
                    error_type: business_rules
                    error_code: freight_provider_id_required
                    message: seller_freight_provider_id is required.
        '404':
          description: >-
            The carrier returned no tracking information for the number
            (`freight_tracking_not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/insurance/shipsurance/add_funds:
    summary: Shipsurance
    description: >
      [Shipsurance](https://www.shipsurance.com/) is a shipping insurance
      company offering coverage for shipments sent via the major shipping
      carriers worldwide.
    patch:
      summary: Add funds to insurance
      description: >
        You may need to auto fund your account from time to time. For example,
        if you don't normally ship items over $100,

        and may want to add funds to insurance rather than keeping the account
        funded.
      deprecated: true
      tags:
        - insurance
      operationId: add_funds_to_insurance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/add_funds_to_insurance_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/add_funds_to_insurance_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/insurance/shipsurance/balance:
    summary: Shipsurance
    description: >
      [Shipsurance](https://www.shipsurance.com/) is a shipping insurance
      company offering coverage for shipments sent via the major shipping
      carriers worldwide.
    get:
      summary: Get insurance funds balance
      description: Retrieve the balance of your Shipsurance account.
      deprecated: true
      tags:
        - insurance
      operationId: get_insurance_balance
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_insurance_balance_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels:
    summary: Print shipping labels
    description: >
      Print shipping labels for any of the top global carriers in
      minutes—instead of weeks. Simply connect your existing carrier accounts in
      the API dashboard, and then begin creating labels using a carrier service.
    get:
      summary: List labels
      description: >
        This endpoint returns a list of labels that you've created. You can
        optionally filter the results as well as control their sort order and
        the number of results returned at a time.


        By default, all labels are returned, 25 at a time, starting with the
        most recently created ones.  You can combine multiple filter options to
        narrow-down the results.  For example, if you only want to get your UPS
        labels for your east coast warehouse you could query by both
        `warehouse_id` and `carrier_id`
      tags:
        - labels
      operationId: list_labels
      parameters:
        - name: label_status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/label_status'
          description: Only return labels that are currently in the specified status
        - name: service_code
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/service_code'
          example: usps_first_class_mail
          description: Only return labels for a specific carrier service
        - description: Only return labels for a specific carrier account
          name: carrier_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
        - description: Only return labels with a specific tracking number
          name: tracking_number
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: '9405511899223197428490'
        - description: Only return labels that were created in a specific batch
          name: batch_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
        - name: rate_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
          description: Rate ID
        - name: shipment_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
          description: Shipment ID
        - name: external_shipment_id
          in: query
          required: false
          schema:
            type: string
          example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae
          description: Only return labels for a specific external shipment ID.
        - description: Only return labels that originate from a specific warehouse
          name: warehouse_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
        - description: >-
            Only return labels that were created on or after a specific
            date/time
          name: created_at_start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
        - description: >-
            Only return labels that were created on or before a specific
            date/time
          name: created_at_end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
        - description: Only return labels with specific refund status/es.
          name: refund_status
          in: query
          required: false
          explode: false
          schema:
            type: array
            items:
              title: refund_status
              type: string
              enum:
                - request_scheduled
                - pending
                - approved
                - rejected
                - excluded
              description: >
                The status of a Refund Assist request for eligible labels.


                |Status              |Description

                |:-------------------|:-----------------------------------------------------

                |`request_scheduled` |The refund request has been scheduled but
                not yet submitted

                |`pending`           |The refund request has been submitted and
                is awaiting approval

                |`approved`          |The refund request has been approved by
                the carrier

                |`rejected`          |The refund request has been rejected by
                the carrier

                |`excluded`          |The refund request has been excluded by
                the user. Labels in this status were not sent to the carrier for
                a refund request.
          example:
            - pending
            - approved
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          example: 2
          description: >
            Return a specific page of results. Defaults to the first page. If
            set to a number that's greater than the number of pages of results,
            an empty page is returned.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 25
          example: 50
          description: The number of results to return per response.
        - name: sort_dir
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/sort_dir'
            default: desc
          description: Controls the sort order of the query.
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - modified_at
              - created_at
              - voided_at
            default: created_at
          description: Controls which field the query is sorted by.
      responses:
        '200':
          description: >
            The response includes a `labels` array containing a page of results
            (as determined by the `page_size` query parameter).  It also
            includes other useful information, such as the total number of
            labels that match the query criteria, the number of pages of
            results, and the URLs of the first, last, next, and previous pages
            of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_labels_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Purchase label
      description: Purchase and print a label for shipment
      tags:
        - labels
      operationId: create_label
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_label_request_body'
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_label_response_body'
              example:
                label_id: se-2135218
                status: completed
                shipment_id: se-11310579
                ship_date: '2026-05-04T07:00:00Z'
                created_at: '2026-05-04T12:24:34.4153952Z'
                shipment_cost:
                  currency: usd
                  amount: 83.86
                insurance_cost:
                  currency: usd
                  amount: 0
                requested_comparison_amount:
                  currency: usd
                  amount: 0
                rate_details:
                  - rate_detail_type: shipping
                    carrier_description: Shipping
                    carrier_billing_code: BaseServiceCharge
                    carrier_memo: ''
                    amount:
                      currency: usd
                      amount: 59.07
                    billing_source: carrier
                  - rate_detail_type: additional_fees
                    carrier_description: Surge Fee
                    carrier_billing_code: '434'
                    carrier_memo: ''
                    amount:
                      currency: usd
                      amount: 0.96
                    billing_source: carrier
                  - rate_detail_type: prepaid_duties
                    carrier_description: Duties and Taxes (Guaranteed)
                    carrier_billing_code: ''
                    carrier_memo: ''
                    amount:
                      currency: usd
                      amount: 0
                    billing_source: dutiestax
                  - rate_detail_type: prepaid_taxes
                    carrier_description: Duties and Taxes (Guaranteed)
                    carrier_billing_code: ''
                    carrier_memo: ''
                    amount:
                      currency: usd
                      amount: 13.43
                    billing_source: dutiestax
                  - rate_detail_type: prepaid_import_fees
                    carrier_description: Duties and Taxes (Guaranteed)
                    carrier_billing_code: ''
                    carrier_memo: ''
                    amount:
                      currency: usd
                      amount: 10.4
                    billing_source: dutiestax
                tracking_number: 1Z2A863C6620022614
                is_return_label: false
                is_international: true
                batch_id: se-0
                carrier_id: se-440144
                charge_event: carrier_default
                service_code: ups_worldwide_express
                package_code: package
                voided: false
                label_format: pdf
                display_scheme: label
                label_layout: 4x6
                trackable: true
                carrier_code: ups
                tracking_status: in_transit
                label_download:
                  href: https://api.shipengine.com/v1/downloads/label-2135218.pdf
                  pdf: https://api.shipengine.com/v1/downloads/label-2135218.pdf
                  png: https://api.shipengine.com/v1/downloads/label-2135218.png
                  zpl: https://api.shipengine.com/v1/downloads/label-2135218.zpl
                form_download:
                  href: https://api.shipengine.com/v1/downloads/form-2135218.pdf
                packages: []
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/rates/{rate_id}:
    summary: Use a rate to purchase a label
    description: >-
      Purchase a label using a `rate_id` that has been previously generated
      while looking at various rates for a particular shipment.
    parameters:
      - name: rate_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Rate ID
    post:
      summary: Purchase label with rate ID
      description: >
        When retrieving rates for shipments using the `/rates` endpoint, the
        returned information contains a `rate_id` property that can be used

        to generate a label without having to refill in the shipment information
        repeatedly.
      tags:
        - labels
      operationId: create_label_from_rate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_label_from_rate_request_body'
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_label_from_rate_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/rate_shopper_id/{rate_shopper_id}:
    summary: Use Rate Shopper to purchase a label
    description: >
      Automatically select the optimal carrier and service based on your

      specified strategy or custom rate shopper configuration, then purchase

      a label.


      **Standard strategies** (`cheapest`, `fastest`, `best_value`): The Rate

      Shopper analyzes available rates across your connected carriers and
      selects

      the best option according to the chosen strategy.


      **Custom rate shoppers** (service collection GUID): Uses your configured

      service collection to determine which carrier/service combinations are

      eligible, applies transit time filtering (with separate
      domestic/international

      thresholds), and selects the cheapest qualifying rate. This feature
      requires

      an Advanced plan. Free plan can only use the default standard strategies.
    parameters:
      - name: rate_shopper_id
        in: path
        required: true
        description: >
          The rate selection strategy or custom rate shopper ID.


          **Standard strategies:**

          - `cheapest`: Lowest cost option

          - `fastest`: Fastest option at the lowest price

          - `best_value`: Lowest cost option arriving within 4 days


          **Custom rate shopper:**

          Pass a service collection GUID (e.g.,
          `f47ac10b-58cc-4372-a567-0e02b2c3d479`)

          to use a custom rate shopper configuration. The service collection
          must be

          active and owned by the authenticated seller.
        schema:
          type: string
        examples:
          standard:
            value: cheapest
            summary: Standard strategy using the cheapest option
          custom:
            value: f47ac10b-58cc-4372-a567-0e02b2c3d479
            summary: Custom rate shopper using a service collection GUID
    post:
      summary: Use rate shopper to purchase a label
      description: >
        Purchase and print a shipping label using the Rate Shopper. The Rate

        Shopper automatically selects the optimal carrier and service from your

        wallet carriers based on the specified strategy or custom rate shopper

        configuration.


        You can use a standard strategy (`cheapest`, `fastest`, `best_value`)

        or pass a custom rate shopper ID (service collection GUID) to use your

        own configured service collection for rate selection.


        For more information about Rate Shopper strategies and use cases, see
        the rates

        documentation.
      tags:
        - labels
      operationId: create_label_from_rate_shopper
      parameters:
        - name: rate_shopper_id
          in: path
          required: true
          description: >
            The rate selection strategy or custom rate shopper ID.


            **Standard strategies:**

            - `cheapest`: Lowest cost option

            - `fastest`: Fastest option at the lowest price

            - `best_value`: Lowest cost option arriving within 4 days


            **Custom rate shopper:**

            Pass a service collection GUID (e.g.,
            `f47ac10b-58cc-4372-a567-0e02b2c3d479`)

            to use a custom rate shopper configuration. The service collection
            must be

            active and owned by the authenticated seller.
          schema:
            type: string
          examples:
            standard:
              value: cheapest
              summary: Standard strategy using the cheapest option
            custom:
              value: f47ac10b-58cc-4372-a567-0e02b2c3d479
              summary: Custom rate shopper using a service collection GUID
      requestBody:
        description: Label creation details with inline shipment
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_label_rate_shopper_request_body'
            examples:
              domestic_shipment:
                summary: Domestic shipment with rate shopper
                value:
                  shipment:
                    ship_to:
                      name: John Doe
                      company_name: Example Corp
                      address_line1: 123 Main St
                      city_locality: Austin
                      state_province: TX
                      postal_code: '78701'
                      country_code: US
                      phone: 512-555-1234
                    ship_from:
                      name: Warehouse A
                      address_line1: 456 Warehouse Blvd
                      city_locality: Dallas
                      state_province: TX
                      postal_code: '75001'
                      country_code: US
                    packages:
                      - weight:
                          value: 5
                          unit: pound
                        dimensions:
                          length: 12
                          width: 8
                          height: 6
                          unit: inch
                  label_format: pdf
                  label_layout: 4x6
      responses:
        '200':
          description: >
            Label created successfully using Rate Shopper. The response includes
            the

            selected carrier_id, service_code, and rate_shopper_id that was
            used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_label_rate_shopper_response_body'
              examples:
                successful_label:
                  summary: Successfully created label
                  value:
                    label_id: se-123456
                    status: completed
                    shipment_id: se-789012
                    ship_date: '2026-02-25T00:00:00Z'
                    created_at: '2026-02-25T10:30:00Z'
                    shipment_cost:
                      currency: usd
                      amount: 7.33
                    insurance_cost:
                      currency: usd
                      amount: 0
                    tracking_number: 1Z999AA10123456784
                    is_return_label: false
                    rma_number: null
                    is_international: false
                    batch_id: se-987654
                    carrier_id: se-456789
                    service_code: usps_priority_mail
                    package_code: package
                    voided: false
                    label_format: pdf
                    label_layout: 4x6
                    trackable: true
                    carrier_code: stamps_com
                    tracking_status: in_transit
                    label_download:
                      pdf: >-
                        https://api.shipengine.com/v1/downloads/10/label-123456.pdf
                      png: >-
                        https://api.shipengine.com/v1/downloads/10/label-123456.png
                      zpl: >-
                        https://api.shipengine.com/v1/downloads/10/label-123456.zpl
                      href: >-
                        https://api.shipengine.com/v1/downloads/10/label-123456.pdf
                    form_download:
                      href: >-
                        https://api.shipengine.com/v1/downloads/10/form-123456.pdf
                    insurance_claim:
                      href: https://api.shipengine.com/v1/claims/123456
                    packages: []
                    charge_event: carrier_default
                    rate_shopper_id: cheapest
        '400':
          description: >
            Bad Request. Possible causes:

            - Request body is missing

            - `rate_shopper_id` is not a valid standard strategy or GUID

            - Custom rate shopper not found (invalid GUID or not owned by
            seller)

            - Custom rate shopper is not active

            - No rates available for the shipment

            - Unable to resolve carrier and service using the specified custom
            rate shopper
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/shipping_rules/{shipping_rule_id}:
    summary: Purchase label using a shipping rule
    description: >
      Purchase and print a label using a Shipping Rule to automatically select
      carrier and service based on the configured rule.
    parameters:
      - name: shipping_rule_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Shipping Rule ID
    post:
      summary: Purchase label with shipping rule
      description: >
        Purchase and print a shipping label using a Shipping Rule. The Shipping
        Rule automatically selects the optimal carrier and service based on the
        rule's configuration.


        **Dynamic Ordering**: Service Group Rules can now use dynamic ordering
        (_Cheapest_ or _Fastest_) to automatically rank eligible services in
        real time based on live rate or transit data. This feature is currently
        available for US sellers with USA domestic carrier services only. For
        more details, see the [Configuring "Order Services By"
        guide](/apis/@shipengine/docs/shipping/shipping-rules-configuring-order-services-by.md).


        The request body must NOT include `carrier_id`, `service_code`, or
        `shipping_rule_id` in the shipment object. If any of these fields are
        provided, the API will return a `400 Bad Request` error.
      tags:
        - labels
      operationId: create_label_from_shipping_rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/create_label_from_shipping_rule_request_body
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_label_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/shipment/{shipment_id}:
    summary: Purchase label using shipment ID
    description: >
      Purchase a label using a shipment ID that has already been created with
      the desired address and

      package info.
    parameters:
      - name: shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Shipment ID
    post:
      summary: Purchase label with shipment ID
      description: >
        Purchase a label using a shipment ID that has already been created with
        the desired address and

        package info.
      tags:
        - labels
      operationId: create_label_from_shipment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_label_from_shipment_request_body'
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_label_from_shipment_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/{label_id}:
    summary: Label
    description: Retrieve information for individual labels.
    parameters:
      - name: label_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Label ID
    get:
      summary: Get label by ID
      description: Retrieve information for individual labels.
      tags:
        - labels
      operationId: get_label_by_id
      parameters:
        - name: label_download_type
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/label_download_type'
          example: url
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_label_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/external_shipment_id/{external_shipment_id}:
    summary: Get label by external shipment ID
    description: Find a label using the external shipment id
    parameters:
      - name: external_shipment_id
        in: path
        schema:
          type: string
        required: true
        example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae
    get:
      summary: Get label by external shipment ID
      description: >
        Find a label by using the external shipment id that was used during
        label creation
      tags:
        - labels
      operationId: get_label_by_external_shipment_id
      parameters:
        - name: label_download_type
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/label_download_type'
          example: url
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/get_label_by_external_shipment_id_response_body
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/{label_id}/return:
    summary: Return labels
    parameters:
      - name: label_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Label ID
    post:
      summary: Create a return label
      description: >
        Create a return label for an existing outbound label. You can optionally
        specify a custom RMA (Return Merchandise Authorization) number. If no
        RMA number is provided, the system will auto-generate one.
      tags:
        - labels
      operationId: create_return_label
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_return_label_request_body'
            examples:
              with_custom_rma:
                summary: Return label with custom RMA number
                description: Create a return label with a specific RMA number
                value:
                  label_format: pdf
                  label_layout: 4x6
                  charge_event: carrier_default
                  rma_number: RMA-2024-001234
              without_rma:
                summary: Return label with auto-generated RMA
                description: Create a return label using default RMA generation
                value:
                  label_format: pdf
                  label_layout: 4x6
                  charge_event: carrier_default
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_return_label_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/{label_id}/track:
    summary: Tracking a label
    description: >-
      Carriers will provide tracking information so the status of your shipment
      can be monitored
    parameters:
      - name: label_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Label ID
    get:
      summary: Get label tracking information
      description: Retrieve the label's tracking information
      tags:
        - labels
      operationId: get_tracking_log_from_label
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_tracking_log_from_label_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/{label_id}/void:
    summary: Label voiding
    description: >
      Some carriers charge for creating a label upon purchase vs upon use. The
      Shipengine API allows you

      to void a label to get a refund.
    parameters:
      - name: label_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Label ID
    put:
      summary: Void a label by ID
      description: Void a label by ID to get a refund.
      tags:
        - labels
      operationId: void_label
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/void_label_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/{label_id}/cancel_refund:
    summary: Cancel label refund request
    description: >
      Exclude labels from Refund Assist by canceling a scheduled refund request.
      This endpoint allows you to prevent a label with "request_scheduled"
      refund status from being included in an upcoming automatic refund request.
    parameters:
      - name: label_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Label ID
    post:
      summary: Cancel a label refund request
      description: >-
        Cancel a scheduled refund request for a label. Only labels with refund
        status "request_scheduled" can be excluded from an upcoming refund
        request.
      tags:
        - labels
      operationId: cancel_label_refund
      responses:
        '200':
          description: >-
            The refund cancellation was successful. Returns the updated label
            object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cancel_refund_label_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/{label_id}/documents:
    summary: Carrier documents for a label
    description: >
      Register, list, and manage carrier documents (such as commercial invoices
      and certificates of origin) for a purchased label. Carrier details are
      resolved automatically from the label.


      > **Note:** Carrier Document Upload is currently supported for **UPS** and
      **FedEx** only. Accepted document types and file size vary by carrier —
      please refer to the [Carrier Document Upload
      guide](/apis/@shipengine/docs/labels/carrier-document-upload.md) for the
      full list.
    parameters:
      - name: label_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Label ID
    post:
      summary: Register a document for a label
      description: >
        Register a carrier document against a label. The response returns an
        `upload` target; upload the document file to that target, then call the
        send documents endpoint to transmit it to the carrier. Carrier
        information is resolved automatically from the label.
      tags:
        - documents
      operationId: register_label_document
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/register_document_request_body'
      responses:
        '200':
          description: The document was registered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/register_document_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    get:
      summary: List documents for a label
      description: >-
        Retrieve the carrier documents registered against a label, including
        their processing status.
      tags:
        - documents
      operationId: list_label_documents
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_documents_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/{label_id}/documents/{document_id}:
    summary: A carrier document for a label
    parameters:
      - name: label_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Label ID
      - name: document_id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the document.
        example: 7f3c1b2a-9d4e-4f5a-8c6b-2e1d0a9b8c7d
    delete:
      summary: Delete a label document
      description: >-
        Delete a carrier document registered against a label. Documents that
        have already been sent to the carrier cannot be deleted.
      tags:
        - documents
      operationId: delete_label_document
      responses:
        '204':
          description: The document was deleted successfully.
        '404':
          $ref: '#/components/responses/404_error_response'
        '409':
          $ref: '#/components/responses/409_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/labels/{label_id}/documents/send:
    summary: Send a label's documents to the carrier
    parameters:
      - name: label_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Label ID
    post:
      summary: Send label documents
      description: >-
        Transmit all uploaded documents for a label to the carrier. Documents
        must be uploaded to their `upload` target before they can be sent.
      tags:
        - documents
      operationId: send_label_documents
      responses:
        '200':
          description: The documents were sent to the carrier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/send_documents_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
        '503':
          description: The document service is temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
  /v1/documents/{document_id}/download:
    summary: Download a carrier document
    parameters:
      - name: document_id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the document.
        example: 7f3c1b2a-9d4e-4f5a-8c6b-2e1d0a9b8c7d
    get:
      summary: Download a document
      description: Download the file for a previously registered carrier document.
      tags:
        - documents
      operationId: download_document
      responses:
        '200':
          description: The document file.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/404_error_response'
        '410':
          description: The document is invalid and cannot be downloaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
        '425':
          description: The document is still being processed. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
        '500':
          $ref: '#/components/responses/500_error_response'
        '503':
          description: The document service is temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_body'
  /v1/mailing/netstamps:
    summary: Create NetStamps
    description: |
      Create NetStamps (individual stamps with row/column positioning) for USPS.
    post:
      summary: Create netstamps
      description: >
        Create one or more NetStamps. Each shipment in the request produces an
        individual stamp with row/column positioning via
        `advanced_options.netstamps_options`.
      tags:
        - mailing
      operationId: create_netstamps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_netstamps_labels_request_body'
      responses:
        '200':
          description: The labels were created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/multi_label_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/mailing/mail_labels:
    summary: Create mailing labels
    description: |
      Create mailing labels on label sheets with start row/column positioning.
    post:
      summary: Create mailing labels
      description: >
        Create one or more mailing labels on a sheet layout. Use
        `mailing_options` to control which row and column to start printing
        from.
      tags:
        - mailing
      operationId: create_mailing_labels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_mail_labels_request_body'
      responses:
        '200':
          description: The labels were created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/multi_label_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/mailing/envelopes:
    summary: Create envelope
    description: |
      Create a single envelope for USPS.
    post:
      summary: Create envelope
      description: |
        Create a single envelope shipment.
      tags:
        - mailing
      operationId: create_envelope
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_envelope_label_request_body'
      responses:
        '200':
          description: The label was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_label_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/manifests:
    summary: Manifests
    description: >
      Many manifests are sent electronically to the carrier when you create a
      label, and

      often physical manifests are not necessary. Carriers receive the package
      details, shipping date,

      and other information that help them plan your package's delivery when you
      create a label.


      However, some providers, like USPS require manifests when shipping large
      numbers of packages. Think about how long it would take for a delivery
      driver to arrive, pick up 100 packages, and individually scan each of
      them.


      A manifest exists so the carrier can scan the manifest and check in all
      the packages being shipped.
    get:
      summary: List manifests
      description: >-
        Similar to querying shipments, we allow you to query manifests since
        there will likely be a large number over a long period of time.
      tags:
        - manifests
      operationId: list_manifests
      parameters:
        - name: warehouse_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
          description: Warehouse ID
        - name: ship_date_start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2018-09-23T15:00:00.000Z'
          description: ship date start range
        - name: ship_date_end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2018-09-23T15:00:00.000Z'
          description: ship date end range
        - name: created_at_start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
          description: >-
            Used to create a filter for when a resource was created (ex. A
            shipment that was created after a certain time)
        - name: created_at_end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
          description: >-
            Used to create a filter for when a resource was created, (ex. A
            shipment that was created before a certain time)
        - name: carrier_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
          description: Carrier ID
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          example: 2
          description: >
            Return a specific page of results. Defaults to the first page. If
            set to a number that's greater than the number of pages of results,
            an empty page is returned.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 25
          example: 50
          description: The number of results to return per response.
        - name: label_ids
          in: query
          explode: true
          required: false
          schema:
            type: array
            items:
              title: se_id
              type: string
              minLength: 1
              maxLength: 25
              pattern: ^se(-[a-z0-9]+)+$
              example: se-28529731
              description: >-
                A string that uniquely identifies a ShipEngine resource, such as
                a carrier, label, shipment, etc.
            description: Array of label ids
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_manifests_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Create manifest
      description: >
        Each ShipEngine manifest is created for a specific warehouse, so you'll
        need to provide the warehouse_id

        rather than the ship_from address. You can create a warehouse for each
        location that you want to create manifests for.
      tags:
        - manifests
      operationId: create_manifest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_manifest_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_manifest_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/manifests/{manifest_id}:
    summary: Manifest ID
    description: Manifest ID
    parameters:
      - name: manifest_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: The Manifest Id
    get:
      summary: Get manifest by ID
      description: Get Manifest By Id
      tags:
        - manifests
      operationId: get_manifest_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_manifest_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/manifests/requests/{manifest_request_id}:
    summary: Manifest request ID
    description: Manifest Request ID
    parameters:
      - name: manifest_request_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: The Manifest Request Id
    get:
      summary: Get manifest request by ID
      description: Get Manifest Request By Id
      tags:
        - manifests
      operationId: get_manifest_request_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_manifest_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/packages:
    summary: Packages
    description: >
      Sometimes the default package types that carriers provide aren't enough
      and you need to create your own. That's where

      the `/packages` endpoint becomes useful. Create, manage, and delete custom
      package types to suit your specific needs.
    get:
      summary: List custom package types
      description: List the custom package types associated with the account
      tags:
        - package_types
      operationId: list_package_types
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_package_types_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Create custom package type
      description: >-
        Create a custom package type to better assist in getting accurate rate
        estimates
      tags:
        - package_types
      operationId: create_package_type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_package_type_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_package_type_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/packages/{package_id}:
    summary: Package
    description: Create, edit, and delete individual custom packages.
    parameters:
      - name: package_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Package ID
    get:
      summary: Get custom package type by ID
      description: Get Custom Package Type by ID
      tags:
        - package_types
      operationId: get_package_type_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_package_type_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    put:
      summary: Update custom package type by ID
      description: Update the custom package type object by ID
      tags:
        - package_types
      operationId: update_package_type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_package_type_request_body'
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    delete:
      summary: Delete a custom package by ID
      description: Delete a custom package using the ID
      tags:
        - package_types
      operationId: delete_package_type
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/pickups:
    summary: Scheduled pickups
    description: |
      Scheduled package pickups
    get:
      summary: List scheduled pickups
      description: List all pickups that have been scheduled for this carrier
      tags:
        - package_pickups
      operationId: list_scheduled_pickups
      parameters:
        - name: carrier_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
          description: Carrier ID
        - name: warehouse_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
          description: Warehouse ID
        - description: >-
            Only return scheduled pickups that were created on or after a
            specific date/time
          name: created_at_start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
        - description: >-
            Only return scheduled pickups that were created on or before a
            specific date/time
          name: created_at_end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          example: 2
          description: >
            Return a specific page of results. Defaults to the first page. If
            set to a number that's greater than the number of pages of results,
            an empty page is returned.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 25
          example: 50
          description: The number of results to return per response.
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_pickups_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Schedule a pickup
      description: Schedule a package pickup with a carrier
      tags:
        - package_pickups
      operationId: schedule_pickup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/schedule_pickup_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schedule_pickup_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/pickups/{pickup_id}:
    summary: Scheduled pickup
    description: |
      A package pickup that has been scheduled with a carrier
    parameters:
      - name: pickup_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/pickup_resource_id'
    get:
      summary: Get pickup by ID
      description: Get Pickup By ID
      tags:
        - package_pickups
      operationId: get_pickup_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_pickup_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    delete:
      summary: Delete a scheduled pickup
      description: Delete a previously-scheduled pickup by ID
      tags:
        - package_pickups
      operationId: delete_scheduled_pickup
      responses:
        '200':
          description: >
            Return the `pickup_id` of the scheduled pickup that was successfully
            deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete_pickup_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/rates:
    summary: Rates
    description: Get the various rates for a set of carriers
    post:
      summary: Get shipping rates
      description: >
        It's not uncommon that you want to give your customer the choice between
        whether they want to ship the fastest, cheapest, or the most trusted
        route. Most companies don't solely ship things using a single shipping
        option;

        so we provide functionality to show you all your options!
      tags:
        - rates
      operationId: calculate_rates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/calculate_rates_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/calculate_rates_response_body'
              example:
                rate_response:
                  rates:
                    - rate_id: se-7766853
                      rate_type: shipment
                      carrier_id: se-426451
                      shipping_amount:
                        currency: usd
                        amount: 59.07
                      insurance_amount:
                        currency: usd
                        amount: 0
                      confirmation_amount:
                        currency: usd
                        amount: 0
                      other_amount:
                        currency: usd
                        amount: 20.63
                      rate_details:
                        - rate_detail_type: shipping
                          carrier_description: Shipping
                          carrier_billing_code: BaseServiceCharge
                          carrier_memo: ''
                          amount:
                            currency: usd
                            amount: 59.07
                          billing_source: Carrier
                        - rate_detail_type: additional_fees
                          carrier_description: Surge Fee
                          carrier_billing_code: '434'
                          carrier_memo: ''
                          amount:
                            currency: usd
                            amount: 0.96
                          billing_source: Carrier
                        - rate_detail_type: estimated_duties
                          carrier_description: Duties and Taxes (Estimated)
                          carrier_billing_code: ''
                          carrier_memo: ''
                          amount:
                            currency: usd
                            amount: 0
                          billing_source: DutiesTax
                        - rate_detail_type: estimated_taxes
                          carrier_description: Duties and Taxes (Estimated)
                          carrier_billing_code: ''
                          carrier_memo: ''
                          amount:
                            currency: usd
                            amount: 13.43
                          billing_source: DutiesTax
                        - rate_detail_type: estimated_import_fees
                          carrier_description: Duties and Taxes (Estimated)
                          carrier_billing_code: ''
                          carrier_memo: ''
                          amount:
                            currency: usd
                            amount: 6.24
                          billing_source: DutiesTax
                      delivery_days: 1
                      guaranteed_service: true
                      estimated_delivery_date: '2026-05-26T12:00:00Z'
                      carrier_delivery_days: Tuesday 5/26 by 12:00 PM
                      ship_date: '2026-05-22T00:00:00Z'
                      negotiated_rate: false
                      service_type: UPS Worldwide Express®
                      service_code: ups_worldwide_express
                      trackable: true
                      carrier_code: ups
                      carrier_nickname: UPS by ShipStation (USD)
                      carrier_friendly_name: UPS
                      validation_status: valid
                      warning_messages: []
                      error_messages: []
                  invalid_rates: []
                  rate_request_id: se-1224263
                  shipment_id: se-11501596
                  status: completed
                  errors: []
                shipment_id: se-11501596
                ship_date: '2026-05-22T00:00:00Z'
                created_at: '2026-05-22T23:19:47.493Z'
                modified_at: '2026-05-22T23:19:47.087Z'
                shipment_status: pending
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/rates/bulk:
    summary: Bulk rates
    description: Get specific rates for large groups of shipments
    post:
      summary: Get bulk rates
      description: Get Bulk Shipment Rates
      tags:
        - rates
      operationId: compare_bulk_rates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/compare_bulk_rates_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/compare_bulk_rates_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/rates/estimate:
    summary: Rate estimates
    description: Show rate estimations between carriers with basic information.
    post:
      summary: Estimate rates
      description: Get Rate Estimates
      tags:
        - rates
      operationId: estimate_rates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/estimate_rates_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/estimate_rates_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/rates/{rate_id}:
    summary: Rate
    description: Get Individual rate information.
    parameters:
      - name: rate_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Rate ID
    get:
      summary: Get rate by ID
      description: Retrieve a previously queried rate by its ID
      tags:
        - rates
      operationId: get_rate_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_rate_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/rate_shoppers:
    summary: Rate Shoppers
    description: >
      Manage rate shoppers. Rate shoppers define a set of carrier services

      and rules used to automatically select the best rate when purchasing
      labels.

      This includes both default rate shoppers (cheapest, fastest, best_value)

      and custom rate shoppers configured by the seller.
    get:
      summary: List rate shoppers
      description: |
        Retrieve rate shoppers for the authenticated seller. By default this
        returns both the default rate shoppers (cheapest, fastest, best_value)
        and any custom rate shoppers. Use the `type` parameter to filter.
      tags:
        - rate_shoppers
      operationId: list_rate_shoppers
      parameters:
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - custom
          description: |
            Filter rate shoppers by type. When set to `custom`, only
            seller-created rate shoppers are returned (excludes defaults).
            When omitted, both default and custom rate shoppers are returned.
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - name
              - created_at
            default: name
          description: |
            Field to sort results by. Sorting only applies to custom rate
            shoppers; default rate shoppers are always listed first.
        - name: sort_dir
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
          description: Sort direction.
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rate_shopper_list_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/rate_shoppers/{rate_shopper_id}:
    summary: Rate Shopper
    description: Get an individual rate shopper by ID or strategy name.
    parameters:
      - name: rate_shopper_id
        in: path
        required: true
        schema:
          type: string
        description: |
          The rate shopper identifier. Can be one of:

          **Default rate shoppers (strategy name):**
          - `cheapest`: Lowest cost option
          - `fastest`: Fastest option at the lowest price
          - `best_value`: Lowest cost option arriving within 4 days

          **Custom rate shoppers:**
          A UUID (e.g., `f47ac10b-58cc-4372-a567-0e02b2c3d479`) identifying
          a seller-created rate shopper.
        examples:
          default_strategy:
            value: cheapest
            summary: Default rate shopper using the cheapest strategy
          custom_uuid:
            value: f47ac10b-58cc-4372-a567-0e02b2c3d479
            summary: Custom rate shopper by UUID
    get:
      summary: Get rate shopper by ID
      description: |
        Retrieve a single rate shopper by its identifier. Accepts both
        default strategy names (`cheapest`, `fastest`, `best_value`) and
        custom rate shopper UUIDs.
      tags:
        - rate_shoppers
      operationId: get_rate_shopper_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rate_shopper_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/service_points/list:
    summary: Service points
    post:
      summary: List service points
      description: List carrier service points by location
      operationId: service_points_list
      tags:
        - service_points
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/get_service_points_request'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_service_points_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/service_points/{carrier_code}/{country_code}/{service_point_id}:
    summary: Service points
    parameters:
      - name: carrier_code
        in: path
        required: true
        schema:
          type: string
          minLength: 1
        example: stamps_com
        description: Carrier code
      - name: country_code
        in: path
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 2
        example: CA
        description: >
          A two-letter [ISO 3166-1 country
          code](https://en.wikipedia.org/wiki/ISO_3166-1)
      - name: service_point_id
        in: path
        schema:
          type: string
        required: true
        example: '614940'
    get:
      summary: Get service point by ID
      description: Returns a carrier service point by using the service_point_id
      operationId: service_points_get_by_id
      tags:
        - service_points
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_service_point_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments:
    summary: Shipments
    description: >
      Shipments are the gatekeeper to more advanced functionality inside
      ShipEngine. When you create a shipment, we respond with a shipment_id that
      is a unique identifier inside of ShipEngine.

      Additionally, we realize that you may have your own identifier, you can
      set this by setting the `external_shipment_id` field in the request body.
    get:
      summary: List shipments
      description: Get list of Shipments
      tags:
        - shipments
      operationId: list_shipments
      parameters:
        - name: shipment_status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/shipment_status'
        - name: batch_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
          description: Batch ID
        - name: tag
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: Letters_to_santa
          description: >-
            Search for shipments based on the custom tag added to the shipment
            object
        - name: created_at_start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
          description: >-
            Used to create a filter for when a resource was created (ex. A
            shipment that was created after a certain time)
        - name: created_at_end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
          description: >-
            Used to create a filter for when a resource was created, (ex. A
            shipment that was created before a certain time)
        - name: modified_at_start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
          description: >-
            Used to create a filter for when a resource was modified (ex. A
            shipment that was modified after a certain time)
        - name: modified_at_end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
          description: >-
            Used to create a filter for when a resource was modified (ex. A
            shipment that was modified before a certain time)
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          example: 2
          description: >
            Return a specific page of results. Defaults to the first page. If
            set to a number that's greater than the number of pages of results,
            an empty page is returned.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 25
          example: 50
          description: The number of results to return per response.
        - name: sales_order_id
          in: query
          required: false
          schema:
            type: string
          description: Sales Order ID
        - name: sort_dir
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/sort_dir'
            default: desc
          description: Controls the sort order of the query.
        - name: sort_by
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/shipments_sort_by'
          example: modified_at
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_shipments_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Create shipments
      description: Create one or multiple shipments.
      tags:
        - shipments
      operationId: create_shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_shipments_request_body'
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_shipments_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/external_shipment_id/{external_shipment_id}:
    summary: External shipment ID
    description: >
      When a shipment object is created with a custom shipment ID, you can query
      it using this endpoint
    parameters:
      - name: external_shipment_id
        in: path
        schema:
          type: string
        required: true
        example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae
    get:
      summary: Get shipment by external ID
      description: >-
        Query Shipments created using your own custom ID convention using this
        endpint
      tags:
        - shipments
      operationId: get_shipment_by_external_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_shipment_by_external_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/recognize:
    summary: Parse shipping info
    description: >
      Data often enters your system as unstructured text (for example: emails,
      SMS messages, support tickets, or other documents). ShipEngine's
      shipment-recognition API helps you extract meaningful shipping data
      (people's names, addresses, package weights and dimensions, insurance and
      delivery requirements, etc.) from this unstructured text.
    put:
      summary: Parse shipping info
      description: >
        The shipment-recognition API makes it easy for you to extract shipping
        data from unstructured text, including people's names, addresses,
        package weights and dimensions, insurance and delivery requirements, and
        more.


        Data often enters your system as unstructured text (for example: emails,
        SMS messages, support tickets, or other documents). ShipEngine's
        shipment-recognition API helps you extract meaningful, structured data
        from this unstructured text. The parsed shipment data is returned in the
        same structure that's used for other ShipEngine APIs, so you can easily
        use the parsed data to create a shipping label.


        > **Note:** Shipment recognition is currently supported for the United
        States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.
      tags:
        - shipments
      operationId: parse_shipment
      requestBody:
        required: true
        description: >
          The only required field is `text`, which is the text to be parsed. You
          can optionally also provide a `shipment` containing any already-known
          values. For example, you probably already know the `ship_from`
          address, and you may also already know what carrier and service you
          want to use.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/parse_shipment_request_body'
            examples:
              text_only:
                summary: Text only
                description: >
                  This is the simplest way to call the shipment-recognition API.
                  Just pass the text to be parsed and nothing else.
                value:
                  text: >
                    I have a 4oz package that's 5x10x14in, and I need to ship it
                    to Margie McMiller at 3800 North Lamar suite 200 in austin,
                    tx 78652. Please send it via USPS first class and require an
                    adult signature. It also needs to be insured for $400.
              some_known_fields:
                summary: Some known fields
                description: >
                  You can optionally provide a `shipment` object containing any
                  already-known values. For example, you probably already know
                  the `ship_from` address, and you may also already know what
                  carrier and service you want to use.
                value:
                  text: >
                    I have a 4oz package that's 5x10x14in, and I need to ship it
                    to Margie McMiller at 3800 North Lamar suite 200 in austin,
                    tx 78652. Please send it via USPS first class and require an
                    adult signature. It also needs to be insured for $400.
                  shipment:
                    service_code: usps_first_class_mail
                    ship_from:
                      name: Store Manager
                      company_name: My Awesome Store
                      phone: 555-555-5555
                      address_line1: 587 Shotwell St.
                      address_line2: Suite 201
                      city_locality: San Francisco
                      state_province: CA
                      postal_code: '94110'
                      country_code: US
                      address_residential_indicator: 'yes'
      responses:
        '200':
          description: >
            Returns the parsed shipment, as well as a confidence score and a
            list of all the shipping entities that were recognized in the text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/parse_shipment_response_body'
              examples:
                text_only:
                  description: >
                    This response shows that the shipment-recognition API was
                    able to recognize all the shipping entities in the text.
                    Notice that the `ship_from` field is not populated, since it
                    wasn't included in the request or in the parsed text.
                  value:
                    score: 0.9031369611169101
                    shipment:
                      carrier_id: se-118608
                      service_code: usps_first_class_mail
                      confirmation: adult_signature
                      ship_to:
                        name: Margie McMiller
                        company_name: Adult Signature
                        address_line1: 3800 North Lamar
                        address_line2: Suite 200
                        city_locality: Austin
                        state_province: TX
                        postal_code: '78652'
                        address_residential_indicator: unknown
                      packages:
                        - weight:
                            value: 4
                            unit: ounce
                          dimensions:
                            length: 5
                            width: 10
                            height: 14
                            unit: inch
                          insured_value:
                            amount: 400
                            currency: USD
                    entities:
                      - type: weight
                        score: 0.9805313966503588
                        text: 4oz
                        start_index: 9
                        end_index: 11
                        result:
                          value: 4
                          unit: ounce
                      - type: dimensions
                        score: 1
                        text: 5x10x14in
                        start_index: 28
                        end_index: 36
                        result:
                          length: 5
                          width: 10
                          height: 14
                          unit: inch
                      - type: dimension
                        score: 0.9805313966503588
                        text: 14in
                        start_index: 33
                        end_index: 36
                        result:
                          unit: inch
                          value: 14
                      - type: address
                        score: 0.9281558837267101
                        text: >-
                          to Margie McMiller at 3800 North Lamar suite 200 in
                          austin, tx 78652. Please send it via USPS first class
                          and require an adult signature
                        start_index: 61
                        end_index: 196
                        result:
                          direction: to
                          name: Margie McMiller
                          company_name: Adult Signature
                          address_line1: 3800 North Lamar
                          address_line2: Suite 200
                          city_locality: Austin
                          state_province: TX
                          postal_code: '78652'
                      - type: person
                        score: 0.9519646137063122
                        text: Margie McMiller
                        start_index: 64
                        end_index: 78
                        result:
                          value: Margie McMiller
                      - type: address_line
                        score: 0.9805313966503588
                        text: 3800 North Lamar
                        start_index: 83
                        end_index: 98
                        result:
                          line: 1
                          value: 3800 North Lamar
                      - type: number
                        score: 0.9805313966503588
                        text: '3800'
                        start_index: 83
                        end_index: 86
                        result:
                          type: cardinal
                          value: 3800
                      - type: address_line
                        score: 1
                        text: suite 200
                        start_index: 100
                        end_index: 108
                        result:
                          line: 2
                          value: Suite 200
                      - type: dimension
                        score: 0.4792571878834418
                        text: 200 in
                        start_index: 106
                        end_index: 111
                        result:
                          unit: inch
                          value: 200
                      - type: city_locality
                        score: 0.9805313966503588
                        text: austin
                        start_index: 113
                        end_index: 118
                        result:
                          value: Austin
                      - type: state_province
                        score: 0.6082904353940255
                        text: tx
                        start_index: 121
                        end_index: 122
                        result:
                          name: Texas
                          value: TX
                      - type: postal_code
                        score: 0.9519646137063122
                        text: '78652'
                        start_index: 124
                        end_index: 128
                        result:
                          value: 78652
                      - type: carrier
                        score: 0.9519646137063122
                        text: USPS
                        start_index: 150
                        end_index: 153
                        result:
                          name: Stamps.com
                          value: se-118608
                      - type: service
                        score: 0.6082904353940255
                        text: first class
                        start_index: 155
                        end_index: 165
                        result:
                          name: USPS First Class Mail
                          value: usps_first_class_mail
                      - type: number
                        score: 0.9805313966503588
                        text: first
                        start_index: 155
                        end_index: 159
                        result:
                          type: ordinal
                          value: 1
                      - type: company
                        score: 0.9519646137063122
                        text: adult signature
                        start_index: 182
                        end_index: 196
                        result:
                          value: Adult Signature
                      - type: delivery_confirmation
                        score: 0.8530163983409642
                        text: adult signature
                        start_index: 182
                        end_index: 196
                        result:
                          name: Adult Signature
                          value: adult_signature
                      - type: insurance
                        score: 0.8530163983409642
                        text: insured for $400
                        start_index: 219
                        end_index: 234
                        result:
                          value: 400
                          unit: USD
                      - type: insured_value
                        score: 1
                        text: $400
                        start_index: 231
                        end_index: 234
                        result:
                          unit: USD
                          value: 400
                some_known_fields:
                  description: >
                    This response is shows that the shipment-recognition API was
                    able to recognize all the shipping entities in the text.
                    Notice that the `ship_from` and `service_code` fields are
                    populated with the values that were provided in the request.
                  value:
                    score: 0.9031369611169101
                    shipment:
                      carrier_id: se-118608
                      service_code: usps_first_class_mail
                      confirmation: adult_signature
                      ship_to:
                        name: Margie McMiller
                        company_name: Adult Signature
                        address_line1: 3800 North Lamar
                        address_line2: Suite 200
                        city_locality: Austin
                        state_province: TX
                        postal_code: '78652'
                        address_residential_indicator: unknown
                      ship_from:
                        name: Store Manager
                        company_name: My Awesome Store
                        phone: 555-555-5555
                        address_line1: 587 Shotwell St.
                        address_line2: Suite 201
                        city_locality: San Francisco
                        state_province: CA
                        postal_code: '94110'
                        country_code: US
                        address_residential_indicator: 'yes'
                      packages:
                        - weight:
                            value: 4
                            unit: ounce
                          dimensions:
                            length: 5
                            width: 10
                            height: 14
                            unit: inch
                          insured_value:
                            amount: 400
                            currency: USD
                    entities:
                      - type: weight
                        score: 0.9805313966503588
                        text: 4oz
                        start_index: 9
                        end_index: 11
                        result:
                          value: 4
                          unit: ounce
                      - type: dimensions
                        score: 1
                        text: 5x10x14in
                        start_index: 28
                        end_index: 36
                        result:
                          length: 5
                          width: 10
                          height: 14
                          unit: inch
                      - type: dimension
                        score: 0.9805313966503588
                        text: 14in
                        start_index: 33
                        end_index: 36
                        result:
                          unit: inch
                          value: 14
                      - type: address
                        score: 0.9281558837267101
                        text: >-
                          to Margie McMiller at 3800 North Lamar suite 200 in
                          austin, tx 78652. Please send it via USPS first class
                          and require an adult signature
                        start_index: 61
                        end_index: 196
                        result:
                          direction: to
                          name: Margie McMiller
                          company_name: Adult Signature
                          address_line1: 3800 North Lamar
                          address_line2: Suite 200
                          city_locality: Austin
                          state_province: TX
                          postal_code: '78652'
                      - type: person
                        score: 0.9519646137063122
                        text: Margie McMiller
                        start_index: 64
                        end_index: 78
                        result:
                          value: Margie McMiller
                      - type: address_line
                        score: 0.9805313966503588
                        text: 3800 North Lamar
                        start_index: 83
                        end_index: 98
                        result:
                          line: 1
                          value: 3800 North Lamar
                      - type: number
                        score: 0.9805313966503588
                        text: '3800'
                        start_index: 83
                        end_index: 86
                        result:
                          type: cardinal
                          value: 3800
                      - type: address_line
                        score: 1
                        text: suite 200
                        start_index: 100
                        end_index: 108
                        result:
                          line: 2
                          value: Suite 200
                      - type: dimension
                        score: 0.4792571878834418
                        text: 200 in
                        start_index: 106
                        end_index: 111
                        result:
                          unit: inch
                          value: 200
                      - type: city_locality
                        score: 0.9805313966503588
                        text: austin
                        start_index: 113
                        end_index: 118
                        result:
                          value: Austin
                      - type: state_province
                        score: 0.6082904353940255
                        text: tx
                        start_index: 121
                        end_index: 122
                        result:
                          name: Texas
                          value: TX
                      - type: postal_code
                        score: 0.9519646137063122
                        text: '78652'
                        start_index: 124
                        end_index: 128
                        result:
                          value: 78652
                      - type: carrier
                        score: 0.9519646137063122
                        text: USPS
                        start_index: 150
                        end_index: 153
                        result:
                          name: Stamps.com
                          value: se-118608
                      - type: service
                        score: 0.6082904353940255
                        text: first class
                        start_index: 155
                        end_index: 165
                        result:
                          name: USPS First Class Mail
                          value: usps_first_class_mail
                      - type: number
                        score: 0.9805313966503588
                        text: first
                        start_index: 155
                        end_index: 159
                        result:
                          type: ordinal
                          value: 1
                      - type: company
                        score: 0.9519646137063122
                        text: adult signature
                        start_index: 182
                        end_index: 196
                        result:
                          value: Adult Signature
                      - type: delivery_confirmation
                        score: 0.8530163983409642
                        text: adult signature
                        start_index: 182
                        end_index: 196
                        result:
                          name: Adult Signature
                          value: adult_signature
                      - type: insurance
                        score: 0.8530163983409642
                        text: insured for $400
                        start_index: 219
                        end_index: 234
                        result:
                          value: 400
                          unit: USD
                      - type: insured_value
                        score: 1
                        text: $400
                        start_index: 231
                        end_index: 234
                        result:
                          unit: USD
                          value: 400
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/{shipment_id}:
    summary: Get and Update Shipment
    description: Retrieve and Update and individual shipment based on its ID
    parameters:
      - name: shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Shipment ID
    get:
      summary: Get shipment by ID
      description: Get an individual shipment based on its ID
      tags:
        - shipments
      operationId: get_shipment_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_shipment_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    put:
      summary: Update shipment by ID
      description: Update a shipment object based on its ID
      tags:
        - shipments
      operationId: update_shipment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_shipment_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update_shipment_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/{shipment_id}/cancel:
    summary: Cancel shipment
    description: Cancel a Shipment
    parameters:
      - name: shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Shipment ID
    put:
      summary: Cancel a shipment
      description: >
        Mark a shipment cancelled, if it is no longer needed or being used by
        your organized. Any label associated with the shipment needs to be
        voided first

        An example use case would be if a batch label creation job is going to
        run at a set time and only queries `pending` shipments. Marking a
        shipment as cancelled

        would remove it from this process
      tags:
        - shipments
      operationId: cancel_shipments
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/{shipment_id}/rates:
    summary: Shipment rates
    description: >
      Once a shipment is complete with the desired shipping information, you can
      then search for rates available

      based on the carriers associated with your account
    parameters:
      - name: shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Shipment ID
    get:
      summary: Get shipment rates
      description: Get Rates for the shipment information associated with the shipment ID
      tags:
        - shipments
      operationId: list_shipment_rates
      parameters:
        - name: created_at_start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          example: '2019-03-12T19:24:13.657Z'
          description: >-
            Used to create a filter for when a resource was created (ex. A
            shipment that was created after a certain time)
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_shipment_rates_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/tags:
    summary: Shipment tags
    description: >
      Tags associated with the shipment object to be used to organize and query
      shipment items.
    put:
      summary: Update shipments tags
      description: Update Shipments Tags
      tags:
        - shipments
      operationId: shipments_update_tags
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_shipments_tags_request_body'
        required: true
      responses:
        '204':
          description: NoContent
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/user:
    summary: Assign user to shipments
    description: Assign a user to one or more shipments
    post:
      summary: Assign user to shipments
      description: |
        Assigns a user to one or more shipments. You can assign a single user
        to up to 500 shipments at once.
      tags:
        - shipments
      operationId: assign_user_to_shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/assign_user_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assign_user_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/{shipment_id}/tags:
    summary: Shipment tags
    description: >
      Tags associated with the shipment object to be used to organize and query
      shipment items.
    parameters:
      - name: shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Shipment ID
    get:
      summary: Get shipment tags
      description: Get Shipment tags based on its ID
      tags:
        - shipments
      operationId: shipments_list_tags
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tag_shipment_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/{shipment_id}/tags/{tag_name}:
    summary: Shipment tags
    description: >
      Tags associated with the shipment object to be used to organize and query
      shipment items.
    parameters:
      - name: shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Shipment ID
      - name: tag_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/tag_name'
    post:
      summary: Add tag to shipment
      description: Add a tag to the shipment object
      tags:
        - shipments
      operationId: tag_shipment
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tag_shipment_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    delete:
      summary: Remove tag from shipment
      description: Remove an existing tag from the Shipment object
      tags:
        - shipments
      operationId: untag_shipment
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/{shipment_id}/documents:
    summary: Carrier documents for a shipment
    description: >
      Register, list, and manage carrier documents (such as commercial invoices
      and certificates of origin) for a shipment.


      > **Note:** Carrier Document Upload is currently supported for **UPS** and
      **FedEx** only. Accepted document types and file size vary by carrier —
      please refer to the [Carrier Document Upload
      guide](/apis/@shipengine/docs/labels/carrier-document-upload.md) for the
      full list.
    parameters:
      - name: shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Shipment ID
    post:
      summary: Register a document for a shipment
      description: >
        Register a carrier document against a shipment. The response returns an
        `upload` target; upload the document file to that target so it can later
        be sent to the carrier.
      tags:
        - documents
      operationId: register_shipment_document
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/register_document_request_body'
      responses:
        '200':
          description: The document was registered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/register_document_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    get:
      summary: List documents for a shipment
      description: >-
        Retrieve the carrier documents registered against a shipment, including
        their processing status.
      tags:
        - documents
      operationId: list_shipment_documents
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_documents_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/{shipment_id}/documents/{document_id}:
    summary: A carrier document for a shipment
    parameters:
      - name: shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Shipment ID
      - name: document_id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the document.
        example: 7f3c1b2a-9d4e-4f5a-8c6b-2e1d0a9b8c7d
    delete:
      summary: Delete a shipment document
      description: >-
        Delete a carrier document registered against a shipment. Documents that
        have already been sent to the carrier cannot be deleted.
      tags:
        - documents
      operationId: delete_shipment_document
      responses:
        '204':
          description: The document was deleted successfully.
        '404':
          $ref: '#/components/responses/404_error_response'
        '409':
          $ref: '#/components/responses/409_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/shipments/{shipment_id}/labels:
    summary: Shipments and their document statuses
    description: >
      Retrieve the shipments associated with the given id, each with its
      tracking number and the carrier documents registered against it.
    parameters:
      - name: shipment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Shipment ID
    get:
      summary: List shipments and their document statuses
      description: >-
        Retrieve each shipment associated with the given id, including its
        tracking number and registered carrier documents.
      tags:
        - documents
      operationId: list_shipment_label_documents
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_shipment_labels_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/tags:
    summary: Tags
    description: >
      Tags are simple text-based flags or identifiers. Tags can be used as a
      simple label,

      such as Guaranteed_Overnight or Fragile so shipments can be easily queried
      later.
    get:
      summary: Get tags
      description: Get a list of all tags associated with an account.
      tags:
        - tags
      operationId: list_tags
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_tags_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Create a new tag
      description: Create a new tag for customizing how you track your shipments.
      tags:
        - tags
      operationId: create_tag
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_tag_request_body'
      responses:
        '200':
          description: The requested object creation was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_tag_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/tags/{tag_name}:
    summary: Tag
    description: Create and delete tags
    parameters:
      - name: tag_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/tag_name'
    post:
      summary: Create a new tag
      description: >-
        Create a new tag for customizing how you track your shipments
        (deprecated - use POST /v1/tags instead)
      tags:
        - tags
      operationId: create_tag_by_name
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_tag_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    delete:
      summary: Delete tag
      description: Delete a tag that is no longer needed
      tags:
        - tags
      operationId: delete_tag
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/tags/{tag_name}/{new_tag_name}:
    summary: Tag
    description: Update tag name
    parameters:
      - name: tag_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/tag_name'
      - name: new_tag_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/tag_name'
    put:
      summary: Update tag name
      description: >-
        Change a tag name while still keeping the relevant shipments attached to
        it
      tags:
        - tags
      operationId: rename_tag
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/tokens/ephemeral:
    post:
      summary: Get ephemeral token
      description: >-
        This endpoint returns a token that can be passed to an application for
        authorized access.  The lifetime of this token is 10 seconds.
      operationId: tokens_get_ephemeral_token
      parameters:
        - name: redirect
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/redirect'
          description: >-
            Include a redirect url to the application formatted with the
            ephemeral token.
      tags:
        - tokens
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/tokens_get_ephemeral_token_response_body.yaml
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/tracking:
    summary: Tracking a package
    description: >-
      If you generate your labels through ShipEngine, then you can subscribe to
      real-time tracking events for free!
    get:
      summary: Get tracking information
      description: Retrieve package tracking information
      tags:
        - tracking
      operationId: get_tracking_log
      parameters:
        - name: carrier_code
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: stamps_com
          description: >
            A shipping carrier, such as `fedex`, `dhl_express`, `stamps_com`,
            etc.
        - name: tracking_number
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: '9405511899223197428490'
          description: The tracking number associated with a shipment
        - name: carrier_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
          description: Carrier ID
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_tracking_log_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/tracking/start:
    summary: Start tracking a package
    description: >
      Allows you to subscribe to tracking updates for a package. You specify the
      carrier_code and tracking_number of the package,

      and receive notifications via webhooks whenever the shipping status
      changes.
    post:
      summary: Start tracking a package
      description: >
        Allows you to subscribe to tracking updates for a package. You specify
        the carrier_code and tracking_number of the package,

        and receive notifications via webhooks whenever the shipping status
        changes.
      tags:
        - tracking
      operationId: start_tracking
      parameters:
        - name: carrier_code
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: stamps_com
          description: >
            A shipping carrier, such as `fedex`, `dhl_express`, `stamps_com`,
            etc.
        - name: tracking_number
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: '9405511899223197428490'
          description: The tracking number associated with a shipment
        - name: carrier_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
          description: Carrier ID
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/tracking/stop:
    summary: Stop tracking a package
    description: Unsubscribe from tracking updates for a package.
    post:
      summary: Stop tracking a package
      description: Unsubscribe from tracking updates for a package.
      tags:
        - tracking
      operationId: stop_tracking
      parameters:
        - name: carrier_code
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: stamps_com
          description: >
            A shipping carrier, such as `fedex`, `dhl_express`, `stamps_com`,
            etc.
        - name: tracking_number
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: '9405511899223197428490'
          description: The tracking number associated with a shipment
        - name: carrier_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/se_id'
          description: Carrier ID
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/warehouses:
    summary: Warehouses
    description: >
      You likely have one or more warehouse locations that you frequently ship
      from, in which case it would be annoying to have to specify the

      ship_from and return_to addresses on every shipment. The solution is to
      Create a Warehouse, then you can simply pass the warehouse_id instead.
    get:
      summary: List warehouses
      description: Retrieve a list of warehouses associated with this account.
      tags:
        - warehouses
      operationId: list_warehouses
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_warehouses_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    post:
      summary: Create warehouse
      description: >
        Create a warehouse location that you can use to create shipping items by
        simply passing in the generated warehouse id.

        If the return address is not supplied in the request body then it is
        assumed that the origin address is the return address as well
      tags:
        - warehouses
      operationId: create_warehouse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_warehouse_request_body'
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_warehouse_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/warehouses/{warehouse_id}:
    summary: Warehouse
    description: >
      You likely have one or more warehouse locations that you frequently ship
      from, in which case it would be annoying to have to specify the

      ship_from and return_to addresses on every shipment. The solution is to
      Create a Warehouse, then you can simply pass the warehouse_id instead.
    parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Warehouse ID
    get:
      summary: Get warehouse by ID
      description: Retrieve warehouse data based on the warehouse ID
      tags:
        - warehouses
      operationId: get_warehouse_by_id
      responses:
        '200':
          description: The request was a success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_warehouse_by_id_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    put:
      summary: Update warehouse by ID
      description: Update Warehouse object information
      tags:
        - warehouses
      operationId: update_warehouse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_warehouse_request_body'
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    delete:
      summary: Delete warehouse by ID
      description: Delete a warehouse by ID
      tags:
        - warehouses
      operationId: delete_warehouse
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/warehouses/{warehouse_id}/settings:
    summary: Warehouse settings
    description: Warehouse settings
    parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/se_id'
        description: Warehouse ID
    put:
      summary: Update warehouse settings
      description: Update Warehouse settings object information
      tags:
        - warehouses
      operationId: update_warehouse_settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_warehouse_settings_request_body'
      responses:
        '204':
          description: The request was successful.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/checkout_rates:
    summary: Checkout rates configurations
    description: >
      Create a checkout rates configuration or list the configurations on your
      account. A configuration groups the delivery options a buyer can choose
      from at checkout for a single storefront.
    post:
      operationId: create_checkout_rates_config
      summary: Create a checkout rates configuration
      description: >
        Create a checkout rates configuration together with its initial delivery
        options and shared settings. The configuration is returned with a
        generated `config_id` and, for each option, a generated `option_id`.


        For `live_rate` and `local_delivery` options, each service's
        `carrier_id` and `service_code` are validated and resolved against the
        carriers connected to your account.
      tags:
        - checkout_rates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_checkout_rates_config_request_body'
            example:
              options:
                - name: Standard Shipping
                  type: live_rate
                  services:
                    - carrier_id: se-1234567
                      service_code: usps_priority_mail
                  fee_mode: add
                  fee_percentage: 10
                  fallback_mode: flat_rate
                  fallback_rate_amount: 5
                  fallback_rate_currency: USD
                - name: Free Shipping
                  type: free
                - name: Flat Rate Shipping
                  type: flat_rate
                  amount: 4.99
                  currency: USD
              shared_settings:
                calculation_method: by_volume
                dimensions_by_weight:
                  - max_weight:
                      value: 10
                      unit: pound
                    default_dimensions:
                      length: 12
                      width: 9
                      height: 6
                      unit: inch
      responses:
        '201':
          description: The checkout rates configuration was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkout_rates_config_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    get:
      operationId: list_checkout_rates_configs
      summary: List checkout rates configurations
      description: >
        Return a summary of every checkout rates configuration on your account.
        Each entry contains identifying fields only; use [Get a checkout rates
        configuration](#operation/get_checkout_rates_config) to retrieve an
        individual configuration's options and shared settings.
      tags:
        - checkout_rates
      responses:
        '200':
          description: The list of checkout rates configurations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_checkout_rates_configs_response_body'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/checkout_rates/{config_id}:
    summary: A checkout rates configuration
    parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier of the checkout rates configuration.
    get:
      operationId: get_checkout_rates_config
      summary: Get a checkout rates configuration
      description: >
        Retrieve a single checkout rates configuration, including all of its
        delivery options and shared settings.
      tags:
        - checkout_rates
      responses:
        '200':
          description: The requested checkout rates configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkout_rates_config_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/checkout_rates/{config_id}/options:
    summary: Delivery options for a checkout rates configuration
    parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier of the checkout rates configuration.
    post:
      operationId: add_checkout_rates_option
      summary: Add a delivery option
      description: >
        Add a delivery option to an existing checkout rates configuration.
        Option names must be unique within a configuration; adding an option
        whose name already exists returns a `409 Conflict`.
      tags:
        - checkout_rates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/checkout_rates_option_request_body'
      responses:
        '201':
          description: The delivery option was added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkout_rates_option_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '409':
          $ref: '#/components/responses/409_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/checkout_rates/{config_id}/options/{option_id}:
    summary: A delivery option
    parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier of the checkout rates configuration.
      - name: option_id
        in: path
        required: true
        schema:
          type: integer
        description: The unique identifier of the delivery option.
    get:
      operationId: get_checkout_rates_option
      summary: Get a delivery option
      description: >
        Retrieve a single delivery option belonging to a checkout rates
        configuration.
      tags:
        - checkout_rates
      responses:
        '200':
          description: The requested delivery option.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkout_rates_option_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    put:
      operationId: update_checkout_rates_option
      summary: Update a delivery option
      description: >
        Replace the configuration of an existing delivery option. Option names
        must remain unique within a configuration; renaming an option to a name
        already in use returns a `409 Conflict`.
      tags:
        - checkout_rates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/checkout_rates_option_request_body'
      responses:
        '200':
          description: The delivery option was updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkout_rates_option_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '409':
          $ref: '#/components/responses/409_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
    delete:
      operationId: delete_checkout_rates_option
      summary: Delete a delivery option
      description: >
        Marks a delivery option as inactive (`is_active: false`) instead of
        removing it; it still appears in the configuration.
      tags:
        - checkout_rates
      responses:
        '204':
          description: The delivery option was marked inactive.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/empty_response_body'
            application/json:
              schema:
                $ref: '#/components/schemas/empty_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/checkout_rates/{config_id}/quotes:
    summary: Checkout rate quotes
    parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: >-
          The unique identifier of the checkout rates configuration to quote
          against.
    post:
      operationId: calculate_checkout_rates
      summary: Calculate checkout rates
      description: >
        Calculate the shipping rates a buyer should see at checkout for the
        given destination and cart, using the delivery options defined on the
        configuration. The response contains one rate per delivery option that
        produced a price, and each rate carries its own `quote_id` that can be
        retrieved later with [Get a checkout rate
        quote](#operation/get_checkout_rates_quote).
      tags:
        - checkout_rates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/calculate_checkout_rates_request_body'
            example:
              ship_to:
                address_type: residential
                address_line1: 525 S Winchester Blvd
                city_locality: San Jose
                state_province: CA
                postal_code: '95128'
                country_code: US
              items:
                - name: T-Shirt
                  quantity: 2
                  price: 19.99
                  weight:
                    value: 8
                    unit: ounce
                  dimensions:
                    length: 10
                    width: 8
                    height: 1
                    unit: inch
              currency: USD
      responses:
        '200':
          description: The calculated rates for the cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/calculate_checkout_rates_response_body'
        '400':
          $ref: '#/components/responses/400_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
  /v1/checkout_rates/quotes/{quote_id}:
    summary: A checkout rate quote
    parameters:
      - name: quote_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier of a previously calculated rate quote.
    get:
      operationId: get_checkout_rates_quote
      summary: Get a checkout rate quote
      description: >
        Retrieve a previously calculated rate quote, including the destination
        it was calculated for and the rates that were returned.


        > **Note:** Quotes are retained for a limited time. A request for an
        expired or unknown `quote_id` returns `404 Not Found`.
      tags:
        - checkout_rates
      responses:
        '200':
          description: The requested rate quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkout_rates_quote_response_body'
        '404':
          $ref: '#/components/responses/404_error_response'
        '500':
          $ref: '#/components/responses/500_error_response'
servers:
  - url: https://api.shipengine.com
components:
  schemas:
    get_account_settings_response_body:
      title: get_account_settings_response_body
      allOf:
        - $ref: '#/components/schemas/list_account_settings_body'
    list_account_settings_body:
      title: list_account_settings_body
      description: An account settings list response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/account_settings'
    account_settings:
      title: account_settings
      type: object
      description: A ShipEngine account settings response body
      additionalProperties: false
      properties:
        default_label_layout:
          allOf:
            - $ref: '#/components/schemas/default_label_layout'
    default_label_layout:
      title: default_label_layout
      type: string
      enum:
        - 4x6
        - Letter
      description: The possible default label layout values
    error_response_body:
      title: error_response_body
      type: object
      description: An error response body
      required:
        - request_id
        - errors
      additionalProperties: false
      properties:
        request_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: >
            A UUID that uniquely identifies the request id.

            This can be given to the support team to help debug non-trivial
            issues that may occur
        errors:
          type: array
          readOnly: true
          items:
            allOf:
              - $ref: '#/components/schemas/error'
          description: The errors associated with the failed API call
    uuid:
      title: uuid
      type: string
      format: uuid
      minLength: 36
      maxLength: 36
      pattern: >-
        ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
      example: aa3d8e8e-462b-4476-9618-72db7f7b7009
      description: A UUID (a.k.a. GUID) that uniquely identifies a resource
    error:
      title: error
      type: object
      description: |
        The error structure that gets returned with almost all failed API calls
      required:
        - error_source
        - error_type
        - error_code
        - message
      additionalProperties: false
      properties:
        error_source:
          allOf:
            - $ref: '#/components/schemas/error_source'
        error_type:
          allOf:
            - $ref: '#/components/schemas/error_type'
        error_code:
          allOf:
            - $ref: '#/components/schemas/error_code'
        message:
          type: string
          readOnly: true
          example: Body of request cannot be null.
          minLength: 1
          description: An error message associated with the failed API call
        carrier_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >-
            A string that uniquely identifies the carrier that generated the
            error.
        carrier_code:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/carrier_code'
          description: >
            The name of the shipping carrier that generated the error, such as
            `fedex`, `dhl_express`, `stamps_com`, etc.
        field_name:
          type: string
          readOnly: true
          example: shipment.ship_to.phone_number
          description: The name of the field that caused the error
    error_source:
      title: error_source
      type: string
      enum:
        - carrier
        - order_source
        - shipengine
      description: >
        The source of the error, as indicated by the name this informs us if the
        API call failed because of the

        carrier, the order source, or the ShipEngine API itself.
    error_type:
      title: error_type
      type: string
      enum:
        - account_status
        - business_rules
        - validation
        - security
        - system
        - integrations
      description: |
        The type of error
    error_code:
      title: error_code
      type: string
      enum:
        - auto_fund_not_supported
        - batch_cannot_be_modified
        - carrier_conflict
        - carrier_disconnected
        - carrier_not_connected
        - carrier_not_supported
        - confirmation_not_supported
        - default_warehouse_cannot_be_deleted
        - field_conflict
        - field_value_required
        - forbidden
        - identifier_conflict
        - identifiers_must_match
        - insufficient_funds
        - invalid_address
        - invalid_billing_plan
        - invalid_field_value
        - invalid_identifier
        - invalid_status
        - invalid_string_length
        - label_images_not_supported
        - meter_failure
        - order_source_not_active
        - rate_limit_exceeded
        - refresh_not_supported
        - request_body_required
        - return_label_not_supported
        - settings_not_supported
        - subscription_inactive
        - terms_not_accepted
        - tracking_not_supported
        - trial_expired
        - unauthorized
        - unknown
        - unspecified
        - verification_failure
        - warehouse_conflict
        - webhook_event_type_conflict
        - customs_items_required
        - incompatible_paired_labels
        - invalid_charge_event
        - invalid_object
        - no_rates_returned
        - file_not_found
        - shipping_rule_not_found
        - service_not_determined
        - no_rates_returned
        - funding_source_registration_in_progress
        - insurance_failure
        - funding_source_missing_configuration
        - funding_source_error
        - freight_connection_inactive
        - freight_provider_id_required
        - freight_shipment_not_found
        - freight_tracking_not_available
        - freight_tracking_not_found
        - freight_shipment_not_batchable
      description: The error code specified for the failed API Call
    se_id:
      title: se_id
      type: string
      minLength: 1
      maxLength: 25
      pattern: ^se(-[a-z0-9]+)+$
      example: se-28529731
      description: >-
        A string that uniquely identifies a ShipEngine resource, such as a
        carrier, label, shipment, etc.
    carrier_code:
      title: carrier_code
      type: string
      pattern: ^[a-z0-9]+(_[a-z0-9]+)*$
      example: dhl_express
      description: |
        A shipping carrier, such as `fedex`, `dhl_express`, `stamps_com`, etc.
    list_account_settings_images_response_body:
      title: list_account_settings_images_response_body
      allOf:
        - $ref: '#/components/schemas/list_account_images_response_body'
    list_account_images_response_body:
      title: list_account_images_response_body
      description: A list account images response body
      required:
        - images
      additionalProperties: false
      properties:
        images:
          type: array
          readOnly: true
          minItems: 0
          items:
            allOf:
              - title: account_settings_images
                type: object
                description: A ShipEngine account images body
                additionalProperties: false
                properties:
                  label_image_id:
                    readOnly: true
                    allOf:
                      - $ref: '#/components/schemas/image_id'
                    description: >
                      A string that uniquely identifies the image. This ID is
                      generated by ShipEngine when the image is uploaded.
                  name:
                    type: string
                    minLength: 1
                    maxLength: 50
                    example: My logo
                    description: |
                      A human readable name for the image.
                  is_default:
                    type: boolean
                    example: false
                    description: |
                      Indicates whether this image is set as default.
                  image_content_type:
                    allOf:
                      - type: string
                        enum:
                          - image/png
                          - image/jpeg
                        description: The image type
                    description: |
                      The file type of the image.
                  image_data:
                    type: string
                    example: >-
                      iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg==
                    description: |
                      A base64 encoded string representation of the image.
                  created_at:
                    readOnly: true
                    allOf:
                      - $ref: '#/components/schemas/date_time'
                    description: >-
                      The date and time that the image was created in
                      ShipEngine.
                  modified_at:
                    readOnly: true
                    allOf:
                      - $ref: '#/components/schemas/date_time'
                    description: >-
                      The date and time that the image was modified in
                      ShipEngine.
            description: Image
          description: Image List
      allOf:
        - $ref: '#/components/schemas/paged_list_response_body'
    paged_list_response_body:
      title: paged_list_response_body
      type: object
      required:
        - total
        - page
        - pages
        - links
      additionalProperties: true
      properties:
        total:
          type: integer
          minimum: 0
          example: 2750
          description: The total number of items across all pages of results
        page:
          type: integer
          minimum: 1
          example: 1
          description: >-
            The current page number of results.  For example, if there are 80
            results, and the page size is 25, then `page` could be 1, 2, 3, or
            4.  The first three pages would contain 25 items each, and the
            fourth page would contain the five remaining items.
        pages:
          type: integer
          minimum: 0
          example: 4
          description: >-
            The total number of pages of results.  For example, if there are 80
            results, and the page size is 25, then `pages` would be 4.  The
            first three pages would contain 25 items each, and the fourth page
            would contain the five remaining items.  If there are no results,
            then `pages` will be zero.
        links:
          allOf:
            - $ref: '#/components/schemas/pagination_link'
      description: >
        Many ShipEngine endpoints return a paged list of items.  In addition to
        the returned items, these responses also include information about the
        total number of items, the number of pages of results, and URLs of other
        pages of results.
    pagination_link:
      title: pagination_link
      type: object
      description: Helpful links to other pages of results
      required:
        - first
        - last
        - prev
        - next
      additionalProperties: false
      properties:
        first:
          allOf:
            - $ref: '#/components/schemas/link'
          description: >
            The link to the first page of results.  This object will _always_
            have an `href` field. If there are no results, then the first page
            will contain an empty array of items.
        last:
          allOf:
            - $ref: '#/components/schemas/link'
          description: >
            The link to the final page of results.  This object will _always_
            have an `href` field. If there are no results, then the final page
            will contain an empty array of items.
        prev:
          allOf:
            - $ref: '#/components/schemas/optional_link'
          description: >
            The link to the previous page of results.  The `href` field will
            only be set when the `page` is 2 or greater.
        next:
          allOf:
            - $ref: '#/components/schemas/optional_link'
          description: >
            The link to the next page of results.  The `href` field will only be
            set when the `page` is less than `pages`.
    link:
      title: link
      description: A link to a related resource
      required:
        - href
      allOf:
        - $ref: '#/components/schemas/optional_link'
    optional_link:
      title: optional_link
      description: >-
        A link to a related resource, or an empty object if there is no resource
        to link to
      properties:
        href:
          allOf:
            - $ref: '#/components/schemas/url'
          description: The URL of the linked resource, if any
        type:
          type: string
          minLength: 1
          description: >-
            The type of resource, or the type of relationship to the parent
            resource
    url:
      title: url
      type: string
      format: url
      minLength: 1
      example: https://example.com/resource
      description: A URL
    create_account_settings_image_request_body:
      title: create_account_settings_image_request_body
      description: A ShipEngine account settings images request body
      required:
        - name
        - image_content_type
        - image_data
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/account_settings_images'
    account_settings_images:
      title: account_settings_images
      description: A ShipEngine account images body
      additionalProperties: false
      properties:
        label_image_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/image_id'
          description: >
            A string that uniquely identifies the image. This ID is generated by
            ShipEngine when the image is uploaded.
        name:
          type: string
          minLength: 1
          maxLength: 50
          example: My logo
          description: |
            A human readable name for the image.
        is_default:
          type: boolean
          example: false
          description: |
            Indicates whether this image is set as default.
        image_content_type:
          allOf:
            - type: string
              enum:
                - image/png
                - image/jpeg
              description: The image type
          description: |
            The file type of the image.
        image_data:
          type: string
          example: >-
            iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg==
          description: |
            A base64 encoded string representation of the image.
        created_at:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time that the image was created in ShipEngine.
        modified_at:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time that the image was modified in ShipEngine.
    image_id:
      title: image_id
      type: string
      minLength: 4
      example: img_DtBXupDBxREpHnwEXhTfgK
      description: Used to identify an image resource.
    date_time:
      title: date_time
      type: string
      format: date-time
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2})$
      example: '2018-09-23T15:00:00.000Z'
      description: >
        An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that
        represents a date and time.
    get_account_settings_images_response_body:
      title: get_account_settings_images_response_body
      description: A get account images by id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/account_settings_images'
    empty_response_body:
      title: empty_response_body
      type: string
      minLength: 0
      maxLength: 0
    update_account_settings_image_request_body:
      title: update_account_settings_image_request_body
      description: A ShipEngine account settings images request body
      required:
        - is_default
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/account_settings_images'
    parse_address_request_body:
      title: parse_address_request_body
      type: object
      description: >
        The only required field is `text`, which is the text to be parsed. You
        can optionally also provide an `address` containing already-known
        values. For example, you may already know the recipient's name, city,
        and country, and only want to parse the street address into separate
        lines.
      required:
        - text
      additionalProperties: false
      properties:
        text:
          type: string
          minLength: 1
          example: >-
            Margie McMiller at 3800 North Lamar suite 200 in austin, tx.  The
            zip code there is 78652.
          description: The unstructured text that contains address-related entities
        address:
          allOf:
            - $ref: '#/components/schemas/partial_address'
          description: >
            You can optionally provide any already-known address values. For
            example, you may already know the recipient's name, city, and
            country, and only want to parse the street address into separate
            lines.
    partial_address:
      title: partial_address
      type: object
      description: A complete or partial mailing address.
      properties:
        name:
          type: string
          minLength: 1
          example: John Doe
          description: >
            The name of a contact person at this address.  This field may be set
            instead of - or in addition to - the `company_name` field.
        phone:
          type: string
          minLength: 1
          example: +1 204-253-9411 ext. 123
          description: >
            The phone number of a contact person at this address.  The format of
            this phone number varies depending on the country.
        email:
          type: string
          nullable: true
          example: example@example.com
          description: |
            Email for the address owner.
        company_name:
          type: string
          minLength: 1
          nullable: true
          example: The Home Depot
          description: >
            If this is a business address, then the company name should be
            specified here.
        address_line1:
          type: string
          minLength: 1
          example: 1999 Bishop Grandin Blvd.
          description: >
            The first line of the street address.  For some addresses, this may
            be the only line.  Other addresses may require 2 or 3 lines.
        address_line2:
          type: string
          minLength: 1
          nullable: true
          example: Unit 408
          description: >
            The second line of the street address.  For some addresses, this
            line may not be needed.
        address_line3:
          type: string
          minLength: 1
          nullable: true
          example: 'Building #7'
          description: >
            The third line of the street address.  For some addresses, this line
            may not be needed.
        city_locality:
          type: string
          minLength: 1
          example: Winnipeg
          description: The name of the city or locality
        state_province:
          type: string
          minLength: 1
          example: Manitoba
          description: >
            The state or province.  For some countries (including the U.S.) only
            abbreviations are allowed.  Other countries allow the full name or
            abbreviation.
        postal_code:
          allOf:
            - $ref: '#/components/schemas/postal_code'
        country_code:
          allOf:
            - $ref: '#/components/schemas/country_code'
          description: >
            The two-letter [ISO 3166-1 country
            code](https://en.wikipedia.org/wiki/ISO_3166-1)
        address_residential_indicator:
          default: unknown
          example: 'no'
          description: Indicates whether this is a residential address.
          allOf:
            - $ref: '#/components/schemas/address_residential_indicator'
    postal_code:
      title: postal_code
      minLength: 1
      type: string
      example: 78756-3717
      description: postal code
    country_code:
      title: country_code
      type: string
      minLength: 2
      maxLength: 2
      example: CA
      description: >
        A two-letter [ISO 3166-1 country
        code](https://en.wikipedia.org/wiki/ISO_3166-1)
    address_residential_indicator:
      title: address_residential_indicator
      type: string
      enum:
        - unknown
        - 'yes'
        - 'no'
      description: Indicates whether an address is residential.
    parse_address_response_body:
      title: parse_address_response_body
      type: object
      description: >
        The parsed address, as well as a confidence score and a list of all the
        entities that were recognized in the text.
      required:
        - score
        - address
        - entities
      additionalProperties: false
      properties:
        score:
          type: number
          format: double
          minimum: 0
          maximum: 1
          description: >
            A confidence score between zero and one that indicates how certain
            the API is that it understood the text.
        address:
          allOf:
            - $ref: '#/components/schemas/partial_address'
          description: >
            The parsed address.  This address may not be complete, depending on
            how much information was included in the text and how confident the
            API is about each recognized entity.


            > **Note:** The address-recognition API does not currently perform
            any validation of the parsed address, so we recommend that you use
            the address-validation API to ensure that the address is correct.
        entities:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/recognized_entity'
          description: >
            All of the entities that were recognized in the text. An "entity" is
            a single piece of data, such as a city, a postal code, or an address
            line.  Each entity includes the original text and the parsed value.
    recognized_entity:
      title: recognized_entity
      type: object
      description: >
        An entity is a single piece of data that was recognized in unstructured
        text.  For example, a city, a postal code, package dimensions, insured
        value, etc.  Each entity includes the original text and the parsed
        value.
      required:
        - type
        - score
        - text
        - start_index
        - end_index
      additionalProperties: false
      properties:
        type:
          type: string
          minLength: 1
          description: The Entity type (e.g. "weight", "person", "address_line1", etc.)
        score:
          format: double
          minimum: 0
          maximum: 1
          type: number
          description: >
            A confidence score between zero and one that indicates how certain
            the API is that it correctly recognized this entity
        text:
          type: string
          minLength: 1
          description: >-
            The substring from the original text that was recognized as this
            entity
        start_index:
          type: integer
          minimum: 0
          description: >-
            The index of the first character of this entity within the original
            text
        end_index:
          type: integer
          minimum: 0
          description: >-
            The index of the last character of this entity within the original
            text
        result:
          $ref: '#/components/schemas/normalized_entity'
    normalized_entity:
      title: normalized_entity
      type: object
      additionalProperties: true
      properties: {}
      description: >
        The normalized value of the entity.


        Most entity results have a `value` field, which is the normalized value
        of the entity.  For example, if the substring "john doe" was recognized
        as a "person" entity, then the value might be normalized to have proper
        capitalization (e.g. "John Doe").  Or if the substring "ft worth" was
        recognized as a "city" entity, then the value might be normalized to
        "Fort Worth".


        Some entities have other information in addition to, or instead of a
        `value`.  For example, a "dimensions" entity will have separate fields
        for `length`, `width`, `height`, and `unit`.
    validate_address_request_body:
      title: validate_address_request_body
      type: array
      description: An address validation request body
      items:
        allOf:
          - $ref: '#/components/schemas/address_to_validate'
        description: An array of addresses to validate.
    address_to_validate:
      title: address_to_validate
      description: |
        Any residential or business mailing address, anywhere in the world.
      required:
        - address_line1
        - city_locality
        - state_province
        - country_code
      allOf:
        - $ref: '#/components/schemas/partial_address'
    validate_address_response_body:
      title: validate_address_response_body
      type: array
      description: An address validation response body
      items:
        readOnly: true
        allOf:
          - $ref: '#/components/schemas/address_validation_result'
        description: The address validation response body
    address_validation_result:
      title: address_validation_result
      type: object
      description: An address validation result
      required:
        - status
        - original_address
        - matched_address
        - messages
      additionalProperties: false
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/address_validation_status'
        original_address:
          $ref: '#/components/schemas/address'
          description: The original address that was sent for validation
        matched_address:
          allOf:
            - $ref: '#/components/schemas/address'
            - type: object
              nullable: true
              readOnly: true
          description: The matched address found by the Shipengine API
        messages:
          type: array
          readOnly: true
          default: []
          items:
            $ref: '#/components/schemas/response_message'
          description: >-
            The list of messages that were generated during the address
            validation request.
    address_validation_status:
      title: address_validation_status
      type: string
      enum:
        - unverified
        - verified
        - warning
        - error
      description: The possible address validation status values
    address:
      title: address
      description: >
        Any residential or business mailing address, anywhere in the world.


        > **Note:** Either `name` or `company_name` must be set. Both may be
        specified, if relevant.
      required:
        - name
        - address_line1
        - city_locality
        - state_province
        - postal_code
      allOf:
        - $ref: '#/components/schemas/partial_address'
    response_message:
      title: response_message
      type: object
      description: >-
        A response message that displays when additional info is needed for an
        address validation request.
      additionalProperties: false
      required:
        - code
        - message
        - type
        - detail_code
      properties:
        code:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/address_validation_code'
        message:
          type: string
          readOnly: true
          example: Invalid Postal Code
          minLength: 1
          description: Message explaining the address validation error
        type:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/address_validation_message_type'
        detail_code:
          allOf:
            - $ref: '#/components/schemas/address_validation_detail_code'
            - type: string
              nullable: true
    address_validation_code:
      title: address_validation_code
      type: string
      enum:
        - a1000
        - a1001
        - a1002
        - a1003
        - a1004
        - a1005
        - a1006
        - a1007
        - a1008
        - r1000
        - r1001
        - r1002
        - r1003
      description: The error codes that can be returned by the address validation API
    address_validation_message_type:
      title: address_validation_message_type
      type: string
      enum:
        - error
        - warning
        - info
      description: >-
        The different types of messages that can be returned by the address
        validation API
    address_validation_detail_code:
      title: address_validation_detail_code
      type: string
      enum:
        - unsupported_country
        - non_supported_country
        - minimum_postal_code_verification_failed
        - street_does_not_match_unique_street_name
        - multiple_directionals
        - multiple_matches
        - suite_not_valid
        - suite_missing
        - incompatible_paired_labels
        - invalid_house_number
        - missing_house_number
        - invalid_box_number
        - invalid_charge_event
        - missing_box_number
        - missing_cmra_or_private_mail_box_number
        - suite_has_no_secondaries
        - postal_code_changed_or_added
        - state_province_changed_or_added
        - city_locality_changed_or_added
        - urbanization_changed
        - street_name_spelling_changed_or_added
        - street_name_type_changed_or_added
        - street_direction_changed_or_added
        - suite_type_changed_or_added
        - suite_unit_number_changed_or_added
        - double_dependent_locality_changed_or_added
        - subadministrative_area_changed_or_added
        - subnational_area_changed_or_added
        - po_box_changed_or_added
        - premise_type_changed_or_added
        - house_number_changed
        - organization_changed_or_added
        - partially_verified_to_state_level
        - partially_verified_to_city_level
        - partially_verified_to_street_level
        - partially_verified_to_premise_level
        - verified_to_state_level
        - verified_to_city_level
        - verified_to_street_level
        - verified_to_premise_level
        - verified_to_suite_level
        - coded_to_street_lavel
        - coded_to_neighborhood_level
        - coded_to_community_level
        - coded_to_state_level
        - coded_to_rooftop_level
        - coded_to_rooftop_interpolation_level
        - name_max_length_exceeded
        - phone_max_length_exceeded
        - company_name_max_length_exceeded
        - line1_min_max_length
        - line2_max_length_exceeded
        - line3_max_length_exceeded
        - city_locality_max_length_exceeded
        - state_province_max_length_exceeded
        - invalid_postal_code
        - country_invalid_length
        - address_not_found
      description: >-
        The detailed error codes that can be returned by the address validation
        API
    batch_status:
      title: batch_status
      type: string
      enum:
        - open
        - queued
        - processing
        - completed
        - completed_with_errors
        - archived
        - notifying
        - invalid
      description: The possible batch status values
    sort_dir:
      title: sort_dir
      type: string
      enum:
        - asc
        - desc
      description: |
        Controls the sort order of queries

        |Value     |Description
        |:---------|:-----------------------------------------------------
        |`asc`     |Return results in ascending order
        |`desc`    |Return results in descending order
    batches_sort_by:
      title: batches_sort_by
      type: string
      enum:
        - ship_date
        - processed_at
        - created_at
      description: The possible batches sort by values
    list_batches_response_body:
      title: list_batches_response_body
      type: object
      description: A list batch response body
      required:
        - batches
        - total
        - page
        - pages
        - links
      additionalProperties: false
      properties:
        batches:
          type: array
          readOnly: true
          minItems: 0
          items:
            allOf:
              - $ref: '#/components/schemas/batch'
            description: Batch
          description: Batch List
        total:
          type: integer
          format: int64
          readOnly: true
          minimum: 0
          example: 10
          description: The total number of batches the API call returned
        page:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          example: 1
          description: The page that is currently being read
        pages:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          example: 10
          description: The total number of batch pages the API call returned
        links:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/pagination_link'
    batch:
      title: batch
      type: object
      description: >
        Batches are an advanced feature of ShipEngine designed for users who
        need to generate hundreds or

        thousands of labels at a time.
      required:
        - label_layout
        - label_format
        - batch_id
        - batch_number
        - external_batch_id
        - batch_notes
        - created_at
        - processed_at
        - errors
        - process_errors
        - warnings
        - completed
        - forms
        - count
        - batch_shipments_url
        - batch_labels_url
        - batch_errors_url
        - label_download
        - form_download
        - paperless_download
        - status
      additionalProperties: false
      properties:
        label_layout:
          readOnly: true
          default: 4x6
          description: label layout
          allOf:
            - $ref: '#/components/schemas/label_layout'
        label_format:
          readOnly: true
          default: pdf
          allOf:
            - $ref: '#/components/schemas/label_format'
        batch_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the batch
        batch_number:
          readOnly: true
          type: string
          minLength: 0
          description: The batch number.
        external_batch_id:
          type: string
          readOnly: true
          nullable: true
          minLength: 0
          description: A string that uniquely identifies the external batch
        batch_notes:
          type: string
          readOnly: true
          nullable: true
          default: ''
          example: Batch for morning shipment
          description: Custom notes you can add for each created batch
        created_at:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time the batch was created in ShipEngine
        processed_at:
          allOf:
            - $ref: '#/components/schemas/date_time'
            - type: string
              nullable: true
              readOnly: true
          description: The date and time the batch was processed in ShipEngine
        errors:
          type: integer
          format: int32
          readOnly: true
          minimum: 0
          example: 2
          description: The number of errors that occurred while generating the batch
        process_errors:
          type: array
          readOnly: true
          items:
            allOf:
              - $ref: '#/components/schemas/error'
          description: The errors associated with the failed API call
        warnings:
          type: integer
          format: int32
          readOnly: true
          minimum: 0
          example: 1
          description: The number of warnings that occurred while generating the batch
        completed:
          type: integer
          format: int32
          readOnly: true
          minimum: 0
          example: 1
          description: The number of labels generated in the batch
        forms:
          type: integer
          format: int32
          readOnly: true
          minimum: 0
          example: 3
          description: The number of forms for customs that are available for download
        count:
          type: integer
          format: int32
          readOnly: true
          minimum: 0
          example: 2
          description: The total of errors, warnings, and completed properties
        batch_shipments_url:
          allOf:
            - $ref: '#/components/schemas/optional_link'
          description: The batch shipments endpoint
        batch_labels_url:
          allOf:
            - $ref: '#/components/schemas/optional_link'
          description: Link to batch labels query
        batch_errors_url:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/optional_link'
          description: Link to batch errors endpoint
        label_download:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/label_download'
          description: The label download for the batch
        form_download:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/optional_link'
          description: The form download for any customs that are needed
        paperless_download:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/paperless_download'
          description: >-
            The paperless details which may contain elements like `href`,
            `instructions` and `handoff_code`.
        status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/batch_status'
    label_layout:
      title: label_layout
      type: string
      enum:
        - 4x6
        - letter
        - A4
        - A6
      description: >
        The available layouts (sizes) in which shipping labels can be
        downloaded.  The label format determines which sizes are supported.
        `4x6` is supported for all label formats, whereas `letter` (8.5" x 11")
        is only supported for `pdf` format.
    label_format:
      title: label_format
      type: string
      enum:
        - pdf
        - png
        - zpl
      description: >
        The possible file formats in which shipping labels can be downloaded. We
        recommend `pdf` format because it is supported by all carriers, whereas
        some carriers do not support the `png` or `zpl` formats.


        |Label Format  | Supported Carriers

        |--------------|-----------------------------------

        |`pdf`         | All carriers

        |`png`         | `fedex` <br> `stamps_com` <br> `ups` <br> `usps`

        |`zpl`         | `access_worldwide` <br> `apc` <br> `asendia` <br>
        `dhl_global_mail` <br> `dhl_express` <br> `dhl_express_australia` <br>
        `dhl_express_canada` <br> `dhl_express_worldwide` <br> `dhl_express_uk`
        <br> `dpd` <br> `endicia` <br> `fedex` <br> `fedex_uk` <br> `firstmile`
        <br> `imex` <br> `newgistics` <br> `ontrac` <br> `rr_donnelley` <br>
        `stamps_com` <br> `ups` <br> `usps`
    label_download:
      title: label_download
      type: object
      description: >
        Reference to the various downloadable file formats for the generated
        label
      additionalProperties: false
      properties:
        href:
          allOf:
            - $ref: '#/components/schemas/url'
          description: The URL of the linked resource, if any
        pdf:
          allOf:
            - $ref: '#/components/schemas/url'
          description: The URL for the pdf generated label
        png:
          allOf:
            - $ref: '#/components/schemas/url'
          description: The URL for the png generated label
        zpl:
          allOf:
            - $ref: '#/components/schemas/url'
          description: The URL for the zpl generated label
    paperless_download:
      title: paperless_download
      type: object
      description: >
        The paperless details which may contain elements like `href`,
        `instructions` and `handoff_code`.
      additionalProperties: false
      properties:
        href:
          allOf:
            - $ref: '#/components/schemas/url'
          description: The URL of the linked resource, if any
        instructions:
          type: string
          nullable: true
          default: null
          description: |
            The instructions for the paperless download.
        handoff_code:
          type: string
          nullable: true
          default: null
          description: |
            The handoff code for the paperless download.
    create_batch_request:
      title: create_batch_request
      oneOf:
        - $ref: '#/components/schemas/create_batch_request_body'
        - $ref: '#/components/schemas/create_and_process_batch_request_body'
    create_batch_request_body:
      title: create_batch_request_body
      type: object
      description: A create batch request body
      additionalProperties: false
      properties:
        external_batch_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the external batch
        batch_notes:
          type: string
          minLength: 1
          example: This is my batch
          description: Add custom messages for a particular batch
        shipment_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
          description: Array of shipment IDs used in the batch
        rate_ids:
          type: array
          items:
            minLength: 1
            allOf:
              - $ref: '#/components/schemas/se_id'
          description: Array of rate IDs used in the batch
    create_and_process_batch_request_body:
      title: create_and_process_batch_request_body
      type: object
      description: A create and process batch request body
      additionalProperties: false
      properties:
        external_batch_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the external batch
        batch_notes:
          type: string
          minLength: 1
          example: This is my batch
          description: Add custom messages for a particular batch
        shipment_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
          description: Array of shipment IDs used in the batch
        rate_ids:
          type: array
          items:
            minLength: 1
            allOf:
              - $ref: '#/components/schemas/se_id'
          description: Array of rate IDs used in the batch
        process_labels:
          type: object
          description: The information used to process the batch
          properties:
            create_batch_and_process_labels:
              type: boolean
              description: When 'true', the batch will be enqueued for processing
            ship_date:
              allOf:
                - $ref: '#/components/schemas/date_time'
              description: The Ship date the batch is being processed for
            label_layout:
              default: 4x6
              allOf:
                - $ref: '#/components/schemas/label_layout'
            label_format:
              default: pdf
              allOf:
                - $ref: '#/components/schemas/label_format'
            display_scheme:
              default: label
              allOf:
                - $ref: '#/components/schemas/display_scheme'
              description: The display format that the label should be shown in.
    display_scheme:
      title: display_scheme
      type: string
      enum:
        - label
        - paperless
        - label_and_paperless
      description: The display format that the label should be shown in.
    create_batch_response_body:
      title: create_batch_response_body
      description: A create batch response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/batch'
    get_batch_by_external_id_response_body:
      title: get_batch_by_external_id_response_body
      description: A get batch by external id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/batch'
    get_batch_by_id_response_body:
      title: get_batch_by_id_response_body
      description: A get batch by id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/batch'
    add_to_batch_request_body:
      title: add_to_batch_request_body
      description: An add to batch request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/modify_batch'
    modify_batch:
      title: modify_batch
      type: object
      description: A modify batch object
      additionalProperties: false
      properties:
        shipment_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
            description: The Shipment ID to be modified on the batch
          description: The Shipment Ids to be modified on the batch
        rate_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
            description: The Rate ID to be modified on the batch
          description: Array of Rate IDs to be modifed on the batch
    list_batch_errors_response_body:
      title: list_batch_errors_response_body
      type: object
      description: A batch errors response body
      required:
        - errors
        - links
      additionalProperties: false
      properties:
        errors:
          type: array
          readOnly: true
          default: []
          items:
            $ref: '#/components/schemas/batch_response_error'
          description: The errors currently associated with the batch
        links:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/pagination_link'
    batch_response_error:
      title: batch_response_error
      type: object
      description: A batch response error
      additionalProperties: false
      properties:
        error:
          type: string
          readOnly: true
          minLength: 1
          example: Recipient address has not been verified.
          description: Error message associated with the shipment.
        shipment_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the shipment
        external_shipment_id:
          readOnly: true
          type: string
          description: An external shipment id associated with the shipment
    process_batch_request_body:
      title: process_batch_request_body
      type: object
      description: A process batch request body
      additionalProperties: false
      properties:
        ship_date:
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The Ship date the batch is being processed for
        label_layout:
          default: 4x6
          allOf:
            - $ref: '#/components/schemas/label_layout'
        label_format:
          default: pdf
          allOf:
            - $ref: '#/components/schemas/label_format'
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
    remove_from_batch_request_body:
      title: remove_from_batch_request_body
      description: A modify batch request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/modify_batch'
    get_carriers_response_body:
      title: get_carriers_response_body
      allOf:
        - $ref: '#/components/schemas/list_carriers_response_body'
        - $ref: '#/components/schemas/error_response_body'
    list_carriers_response_body:
      title: list_carriers_response_body
      type: object
      description: A carrier list response body
      required:
        - carriers
      properties:
        carriers:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/carrier'
          description: The carrier response body
      allOf:
        - $ref: '#/components/schemas/paged_list_response_body'
    carrier:
      title: carrier
      type: object
      description: |
        A carrier object that represents a provider such as UPS, USPS, DHL, etc
        that has been tied to the current account.
      additionalProperties: false
      properties:
        carrier_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the carrier.
        carrier_code:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/carrier_code'
          description: >
            The shipping carrier who will ship the package, such as `fedex`,
            `dhl_express`, `stamps_com`, etc.
        account_number:
          type: string
          readOnly: true
          minLength: 1
          example: account_570827
          description: The account number that the carrier is connected to.
        requires_funded_amount:
          type: boolean
          readOnly: true
          description: Indicates whether the carrier requires funding to use its services
        balance:
          type: number
          readOnly: true
          example: 3799.52
          minimum: 0
          description: Current available balance
        nickname:
          type: string
          readOnly: true
          minLength: 1
          example: ShipEngine Account - Stamps.com
          description: Nickname given to the account when initially setting up the carrier.
        friendly_name:
          type: string
          readOnly: true
          minLength: 1
          example: Stamps.com
          description: Screen readable name
        funding_source_id:
          type: string
          readOnly: true
          nullable: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: Funding source ID for the carrier
        primary:
          type: boolean
          readOnly: true
          description: >-
            Is this the primary carrier that is used by default when no carrier
            is specified in label/shipment creation
        has_multi_package_supporting_services:
          type: boolean
          readOnly: true
          description: Carrier supports multiple packages per shipment
        allows_returns:
          type: boolean
          readOnly: true
          description: The carrier has services that support return shipments.
        supports_label_messages:
          type: boolean
          readOnly: true
          description: The carrier supports adding custom label messages to an order.
        disabled_by_billing_plan:
          type: boolean
          readOnly: true
          description: >-
            The carrier is disabled by the current ShipEngine account's billing
            plan.
        services:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/service'
          description: A list of services that are offered by the carrier
        packages:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/package_type'
          description: A list of package types that are supported by the carrier
        options:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/carrier_advanced_option'
          description: A list of options that are available to that carrier
        send_rates:
          type: boolean
          readOnly: true
          description: The carrier provides rates for the shipment.
          example: true
        supports_user_managed_rates:
          type: boolean
          readOnly: true
          description: The carrier supports user-managed rates for shipments.
        connection_status:
          type: string
          readOnly: true
          enum:
            - pending_approval
            - approved
          description: >-
            The current connection status of the carrier. Indicates whether the
            carrier connection is pending approval or has been approved for use.
    service:
      title: service
      type: object
      description: A service offered by the carrier
      additionalProperties: false
      properties:
        carrier_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the carrier
        carrier_code:
          allOf:
            - $ref: '#/components/schemas/se_id'
        service_code:
          type: string
          minLength: 1
          readOnly: true
          example: usps_media_mail
          description: service code
        name:
          type: string
          minLength: 1
          readOnly: true
          example: USPS First Class Mail
          description: User friendly service name
        domestic:
          type: boolean
          readOnly: true
          description: Supports domestic shipping
        international:
          type: boolean
          readOnly: true
          description: Supports international shipping.
        is_multi_package_supported:
          type: boolean
          readOnly: true
          description: Carrier supports multiple packages per shipment
        is_return_supported:
          type: boolean
          readOnly: true
          description: This service supports return shipments.
        send_rates:
          type: boolean
          readOnly: true
          description: The service provides rates for the shipment.
          example: true
    package_type:
      title: package_type
      type: object
      description: A package type (generic schema for mixed use).
      required:
        - name
        - package_code
      additionalProperties: false
      properties:
        package_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the package.
        package_code:
          type: string
          minLength: 1
          maxLength: 50
          example: package
          description: A unique identifier for the package type.
        name:
          type: string
          minLength: 1
          maxLength: 50
          example: laptop_box
        dimensions:
          allOf:
            - $ref: '#/components/schemas/dimensions'
          description: The dimensions for the package.
        description:
          type: string
          maxLength: 500
          example: Packaging for laptops
          nullable: true
          description: Provides a helpful description for the package.
    package_type_request:
      title: package_type_request
      type: object
      description: >-
        A custom package type for API requests. Requires custom_ prefix for
        package_code.
      required:
        - name
        - package_code
      additionalProperties: false
      properties:
        package_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the package.
        package_code:
          type: string
          minLength: 8
          maxLength: 50
          pattern: ^custom_[a-z0-9]+(_[a-z0-9]+)*$
          example: custom_laptop_box
          description: >-
            A unique, user-defined identifier for the custom package type. Must
            start with "custom_".
        name:
          type: string
          minLength: 1
          maxLength: 50
          example: laptop_box
        dimensions:
          allOf:
            - $ref: '#/components/schemas/dimensions'
          description: The custom dimensions for the package.
        description:
          type: string
          maxLength: 500
          example: Packaging for laptops
          nullable: true
          description: Provides a helpful description for the custom package.
    package_type_response:
      title: package_type_response
      type: object
      description: >-
        A custom package type from API responses. May include UI-created
        packages without custom_ prefix.
      required:
        - name
        - package_code
      additionalProperties: false
      properties:
        package_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the package.
        package_code:
          type: string
          minLength: 1
          maxLength: 50
          example: package
          description: >-
            A unique identifier for the custom package type. API-created
            packages start with "custom_". UI-created packages may use other
            codes.
        name:
          type: string
          minLength: 1
          maxLength: 50
          example: laptop_box
        dimensions:
          allOf:
            - $ref: '#/components/schemas/dimensions'
          description: The custom dimensions for the package.
        description:
          type: string
          maxLength: 500
          example: Packaging for laptops
          nullable: true
          description: Provides a helpful description for the custom package.
    carrier_provided_package_type:
      title: carrier_provided_package_type
      type: object
      description: >-
        A package type that a carrier provides for shipment. Unlike custom
        packages, carrier packages do not have a package_id.
      required:
        - name
        - package_code
      additionalProperties: false
      properties:
        package_id:
          type: string
          nullable: true
          description: >-
            This field is always null for carrier-provided packages. Package IDs
            are only assigned to custom packages.
          example: null
        package_code:
          allOf:
            - $ref: '#/components/schemas/package_code'
        name:
          type: string
          minLength: 1
          maxLength: 50
          example: Small Flat Rate Box
        dimensions:
          allOf:
            - $ref: '#/components/schemas/dimensions'
          description: The dimensions for the package.
        description:
          type: string
          maxLength: 500
          nullable: true
          example: USPS Small Flat Rate Box
          description: Provides a helpful description for the package.
    package_code:
      title: package_code
      type: string
      minLength: 1
      maxLength: 50
      pattern: ^[a-z0-9]+(_[a-z0-9]+)*$
      example: small_flat_rate_box
      description: >
        A package type, such as `thick_envelope`, `small_flat_rate_box`,
        `large_package`, etc. Use the code `package` for custom or unknown
        package types.
    dimensions:
      title: dimensions
      type: object
      description: The dimensions of a package
      required:
        - unit
        - length
        - width
        - height
      additionalProperties: false
      properties:
        unit:
          default: inch
          allOf:
            - $ref: '#/components/schemas/dimension_unit'
        length:
          type: number
          minimum: 0
          default: 0
          description: The length of the package, in the specified unit
        width:
          type: number
          minimum: 0
          default: 0
          description: The width of the package, in the specified unit
        height:
          type: number
          minimum: 0
          default: 0
          description: The height of the package, in the specified unit
    dimension_unit:
      title: dimension_unit
      type: string
      enum:
        - inch
        - centimeter
      description: The dimension units that are supported by ShipEngine.
    carrier_advanced_option:
      title: carrier_advanced_option
      type: object
      description: Advanced options that are specific to the carrier
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          readOnly: true
          example: contains_alcohol
          description: Name of advanced option
        default_value:
          type: string
          minLength: 1
          readOnly: true
          example: 'false'
          description: Default value of option
        description:
          type: string
          minLength: 0
          readOnly: true
          description: Description of option
    get_carrier_by_id_response_body:
      title: get_carrier_by_id_response_body
      description: A get carrier by id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/carrier'
    add_funds_to_carrier_request_body:
      title: add_funds_to_carrier_request_body
      description: An add funds to carrier request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/monetary_value'
    monetary_value:
      title: monetary_value
      type: object
      description: >
        A monetary value, such as the price of a shipping label, the insured
        value of a package, or an account balance.
      required:
        - currency
        - amount
      additionalProperties: false
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/currency'
        amount:
          type: number
          minimum: 0
          description: The monetary amount, in the specified currency.
    currency:
      title: currency
      type: string
      description: >
        The currencies that are supported by ShipEngine are the ones that
        specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html
    add_funds_to_carrier_response_body:
      title: add_funds_to_carrier_response_body
      type: object
      description: The current balance of the requested carrier account
      required:
        - balance
      additionalProperties: false
      properties:
        balance:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The current balance of the account
    get_carrier_options_response_body:
      title: get_carrier_options_response_body
      type: object
      description: A carrier list options response body
      additionalProperties: false
      properties:
        options:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/carrier_advanced_option'
            description: Carrer options
          description: AN array of carrier options
    list_carrier_package_types_response_body:
      title: list_carrier_package_types_response_body
      type: object
      description: A list carrier package types response body
      additionalProperties: false
      properties:
        packages:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/carrier_provided_package_type'
            description: Carrier package type items
          description: An array of carrier-provided package types
    list_carrier_services_response_body:
      title: list_carrier_services_response_body
      type: object
      description: A carrier list services response body
      additionalProperties: false
      properties:
        services:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/service'
            description: A carrier service
          description: An array of services associated with the carrier
    carrier_name:
      title: carrier_name
      type: string
      enum:
        - access_worldwide
        - amazon_buy_shipping
        - amazon_shipping_uk
        - apc
        - asendia
        - australia_post
        - canada_post
        - dhl_ecommerce
        - dhl_express
        - dhl_express_au
        - dhl_express_ca
        - dhl_express_uk
        - dpd
        - endicia
        - fedex
        - fedex_uk
        - firstmile
        - imex
        - newgistics
        - ontrac
        - purolator_canada
        - royal_mail
        - rr_donnelley
        - seko
        - sendle
        - stamps_com
        - ups
        - lasership
      description: The shipping carriers that are supported by ShipEngine
    connect_carrier_request_body:
      title: connect_carrier_request_body
      oneOf:
        - $ref: '#/components/schemas/connect_access_worldwide_request_body'
        - $ref: '#/components/schemas/connect_amazon_buy_shipping_request_body'
        - $ref: '#/components/schemas/connect_amazon_shipping_uk'
        - $ref: '#/components/schemas/connect_apc_request_body'
        - $ref: '#/components/schemas/connect_asendia_request_body'
        - $ref: '#/components/schemas/connect_australia_post_request_body'
        - $ref: '#/components/schemas/connect_canada_post_request_body'
        - $ref: '#/components/schemas/connect_dhl_ecommerce_request_body'
        - $ref: '#/components/schemas/connect_dhl_express_request_body'
        - $ref: '#/components/schemas/connect_dhl_express_au_request_body'
        - $ref: '#/components/schemas/connect_dhl_express_ca_request_body'
        - $ref: '#/components/schemas/connect_dhl_express_uk_request_body'
        - $ref: '#/components/schemas/connect_dpd_request_body'
        - $ref: '#/components/schemas/connect_endicia_request_body'
        - $ref: '#/components/schemas/connect_fedex_request_body'
        - $ref: '#/components/schemas/connect_fedex_uk_request_body'
        - $ref: '#/components/schemas/connect_firstmile_request_body'
        - $ref: '#/components/schemas/connect_imex_request_body'
        - $ref: '#/components/schemas/connect_lasership_request_body'
        - $ref: '#/components/schemas/connect_newgistics_request_body'
        - $ref: '#/components/schemas/connect_ontrac_request_body'
        - $ref: '#/components/schemas/connect_purolator_request_body'
        - $ref: '#/components/schemas/connect_royal_mail_request_body'
        - $ref: '#/components/schemas/connect_rr_donnelley_request_body'
        - $ref: '#/components/schemas/connect_seko_request_body'
        - $ref: '#/components/schemas/connect_sendle_request_body'
        - $ref: '#/components/schemas/connect_stamps_request_body'
        - $ref: '#/components/schemas/connect_ups_request_body'
    connect_access_worldwide_request_body:
      title: connect_access_worldwide_request_body
      type: object
      description: An Access Worldwide account information request body
      required:
        - nickname
        - username
        - password
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          example: Stamps.com
          description: The nickname associated with the carrier connection
        username:
          type: string
          minLength: 1
          description: Access Worldwide Username
        password:
          type: string
          minLength: 1
          description: Access Worldwide Password
    connect_amazon_buy_shipping_request_body:
      title: connect_amazon_buy_shipping_request_body
      type: object
      description: An Amazon account information request body
      required:
        - nickname
        - merchant_seller_id
        - email
        - mws_auth_token
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          example: Test Amazon Buy Shipping
          description: Nickname to be associated with the account connection
        merchant_seller_id:
          type: string
          minLength: 1
        mws_auth_token:
          type: string
          minLength: 1
        email:
          allOf:
            - $ref: '#/components/schemas/email'
    email:
      title: email
      type: string
      format: email
      minLength: 1
      example: john.doe@example.com
      description: An email address.
    connect_amazon_shipping_uk:
      title: connect_amazon_shipping_uk
      type: object
      description: An Amazon Shipping UK account information request body
      required:
        - nickname
        - auth_code
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          example: Stamps.com
          description: The nickname associated with the carrier connection
        auth_code:
          type: string
          minLength: 1
          description: Amazon UK Shipping auth code.
    connect_apc_request_body:
      title: connect_apc_request_body
      type: object
      description: An APC account information request body
      required:
        - nickname
        - username
        - password
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          example: APC carrier account
          description: The nickname for the APC account
        username:
          type: string
          minLength: 1
          example: john_doe
          description: The username for the APC account
        password:
          type: string
          minLength: 1
          example: '12345'
          description: The password for the APC account
    connect_asendia_request_body:
      title: connect_asendia_request_body
      type: object
      description: An Asendia account information request body
      required:
        - nickname
        - account_number
        - username
        - password
        - api_key
        - processing_location
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          example: Asendia account
          description: The nickname of the Asendia account
        account_number:
          type: string
          minLength: 1
          description: Asendia account number
        username:
          type: string
          minLength: 1
          description: Asendia username
        password:
          type: string
          minLength: 1
          description: Asendia password
        api_key:
          type: string
          minLength: 1
          description: Asendia api_key
        processing_location:
          type: string
          minLength: 1
          description: >-
            Asendia processing location, one of: 'MIA', 'JFK', 'ORD', 'PHL',
            'SFO', 'LAX', 'SLC', 'TOR', 'BUF', 'CAL'
        sub_account_number:
          type: string
          minLength: 1
          description: Asendia sub account number
    connect_australia_post_request_body:
      title: connect_australia_post_request_body
      type: object
      description: An Australia Post account information request body
      required:
        - account_number
        - api_key
        - api_secret
        - nickname
      additionalProperties: false
      properties:
        account_number:
          type: string
          minLength: 1
          description: Account number
        api_key:
          type: string
          minLength: 1
          description: API key
        api_secret:
          type: string
          minLength: 1
          description: API secret
        nickname:
          type: string
          minLength: 1
          description: Nickname
    connect_canada_post_request_body:
      title: connect_canada_post_request_body
      type: object
      description: A Canada Post account information request body
      required:
        - nickname
        - api_key
        - api_secret
        - account_number
        - contract_id
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        api_key:
          type: string
          minLength: 1
          description: Canada Post Account API Key
        api_secret:
          type: string
          minLength: 1
          description: Canada Post Account API Secret
        account_number:
          type: string
          minLength: 1
          description: Canada Post Account Number
        contract_id:
          type: string
          minLength: 1
          description: Canada Post Account Contract ID
    connect_dhl_ecommerce_request_body:
      title: connect_dhl_ecommerce_request_body
      type: object
      description: A DHL Ecommerce account information request body
      required:
        - nickname
        - client_id
        - username
        - password
        - pickup_number
        - distribution_center
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: A nickname to help you identify this account
        client_id:
          type: string
          minLength: 1
          description: The client id
        username:
          type: string
          minLength: 1
          description: The account username
        password:
          type: string
          minLength: 1
          description: The account password
        pickup_number:
          type: string
          minLength: 1
          description: The pickup number
        distribution_center:
          type: string
          minLength: 1
          description: The distribution center
        api_key:
          type: string
          minLength: 1
          description: >
            The DHL E-Commerce API key. This field is optional, but if not set
            you will not be able to get rates for this account.
        api_secret:
          type: string
          minLength: 1
          description: >
            The DHL E-Commerce API secret. This field is optional, but if not
            set you will not be able to get rates for this account.
        ancillary_endorsement:
          allOf:
            - $ref: '#/components/schemas/ancillary_service_endorsement'
        account_number:
          type: string
          minLength: 1
          deprecated: true
          description: Account number
        ftp_username:
          type: string
          minLength: 1
          deprecated: true
          description: FTP username
        ftp_password:
          type: string
          minLength: 1
          deprecated: true
          description: FTP password
        sold_to:
          type: string
          description: Sold To field
        registration_id:
          type: string
        software_name:
          type: string
    ancillary_service_endorsement:
      title: ancillary_service_endorsement
      type: string
      enum:
        - none
        - return_service_requested
        - forwarding_service_requested
        - address_service_requested
        - change_service_requested
        - leave_if_no_response
      description: >
        [Ancillary service
        endorsements](https://pe.usps.com/text/qsg300/Q507.htm) are used by
        mailers to request an addressee's new address and to provide the carrier
        with instructions on how to handle packages that are undeliverable as
        addressed.


        | Ancillary Service Endorsement  | Description

        |--------------------------------|-----------------------------------------------------

        | `none`                         | No ancillary service is requested.
        Depending on the carrier servive, the package may be forwarded,
        returned, or discarded.

        | `return_service_requested`     | The package is returned to the
        sender. If possible, notification of the new address is is included with
        the returned package.

        | `forwarding_service_requested` | Forward the package to the new
        address, if possible; otherwise, return it to the sender.

        | `address_service_requested`    | Forward the package to the new
        address, if possible; otherwise, return it to the sender. This is
        similar to `forwarding_service_requested`, but different restrictions
        and charges may apply.

        | `change_service_requested`     | The package is discarded. If
        possible, notification of the new address is sent to the sender.

        | `leave_if_no_response`         |
    connect_dhl_express_request_body:
      title: connect_dhl_express_request_body
      type: object
      description: A DHL express account information request body
      required:
        - nickname
        - account_number
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        account_number:
          type: string
          minLength: 1
          description: Account number
        site_id:
          type: string
          minLength: 1
          description: Required if password is provided
        password:
          type: string
          minLength: 1
          description: Required if site id is provided
        country_code:
          allOf:
            - $ref: '#/components/schemas/country_code'
    connect_dhl_express_au_request_body:
      title: connect_dhl_express_au_request_body
      type: object
      description: A DHL Express AU account information request body
      required:
        - nickname
        - account_number
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        account_number:
          type: string
          minLength: 1
          description: Account number
    connect_dhl_express_ca_request_body:
      title: connect_dhl_express_ca_request_body
      type: object
      description: A DHL Express CA account information request body
      required:
        - nickname
        - account_number
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        account_number:
          type: string
          minLength: 1
          description: Account number
    connect_dhl_express_uk_request_body:
      title: connect_dhl_express_uk_request_body
      type: object
      description: A DHL Express UK account information request body
      required:
        - account_number
        - site_id
        - password
        - nickname
      additionalProperties: false
      properties:
        account_number:
          type: string
          minLength: 1
          description: Account number
        site_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the site
        password:
          type: string
          minLength: 1
          description: Password
        nickname:
          type: string
          minLength: 1
          description: Nickname
    connect_dpd_request_body:
      title: connect_dpd_request_body
      type: object
      description: A DPD account information request body
      required:
        - account_number
        - password
        - nickname
      additionalProperties: false
      properties:
        account_number:
          type: string
          minLength: 1
          description: Account number
        password:
          type: string
          minLength: 1
          description: Password
        nickname:
          type: string
          minLength: 1
          description: Nickname
    connect_endicia_request_body:
      title: connect_endicia_request_body
      type: object
      description: An Endicia account information request body
      required:
        - nickname
        - account
        - passphrase
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        account:
          type: string
          minLength: 1
          description: Account
        passphrase:
          type: string
          minLength: 1
          description: Passphrase
    connect_fedex_request_body:
      title: connect_fedex_request_body
      type: object
      description: A Fedex account information request body
      required:
        - account_number
        - address1
        - city
        - country_code
        - email
        - first_name
        - last_name
        - phone
        - postal_code
        - state
        - nickname
        - agree_to_eula
      additionalProperties: false
      properties:
        account_number:
          type: string
          minLength: 1
          description: Account number
        address1:
          type: string
          minLength: 1
          description: Address
        address2:
          type: string
          minLength: 1
          description: Address
        city:
          type: string
          minLength: 1
          description: The city
        company:
          type: string
          minLength: 1
          description: The company
        country_code:
          type: string
          minLength: 1
          description: Country code
        email:
          allOf:
            - $ref: '#/components/schemas/email'
          description: The email address
        first_name:
          type: string
          minLength: 1
          description: First name
        last_name:
          type: string
          minLength: 1
          description: Last name
        phone:
          type: string
          minLength: 1
          description: Phone number
        postal_code:
          type: string
          minLength: 1
          description: Postal Code
        state:
          type: string
          minLength: 1
          description: State
        nickname:
          type: string
          minLength: 1
          description: Nickname
        agree_to_eula:
          type: boolean
          description: Boolean signaling agreement to the Fedex End User License Agreement
        meter_number:
          type: string
          minLength: 1
          description: Meter number
    connect_fedex_uk_request_body:
      title: connect_fedex_uk_request_body
      type: object
      description: A Fedex UK account information request body
      required:
        - account_number
        - address1
        - city
        - country_code
        - email
        - first_name
        - last_name
        - phone
        - postal_code
        - state
        - nickname
        - agree_to_eula
      additionalProperties: false
      properties:
        account_number:
          type: string
          minLength: 1
          description: Account number
        address1:
          type: string
          minLength: 1
          description: Address
        address2:
          type: string
          minLength: 1
          description: Address
        city:
          type: string
          minLength: 1
          description: The city
        company:
          type: string
          minLength: 1
          description: The company
        country_code:
          type: string
          minLength: 1
          description: Country code
        email:
          allOf:
            - $ref: '#/components/schemas/email'
          description: The email address
        first_name:
          type: string
          minLength: 1
          description: First name
        last_name:
          type: string
          minLength: 1
          description: Last name
        phone:
          type: string
          minLength: 1
          description: Phone number
        postal_code:
          type: string
          minLength: 1
          description: Postal Code
        state:
          type: string
          minLength: 1
          description: State
        nickname:
          type: string
          minLength: 1
          description: Nickname
        agree_to_eula:
          type: boolean
          description: Boolean signaling agreement to the Fedex End User License Agreement
        meter_number:
          type: string
          minLength: 1
          description: Meter number
    connect_firstmile_request_body:
      title: connect_firstmile_request_body
      type: object
      description: A First Mile account information request body
      required:
        - nickname
        - mailer_id
        - password
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        mailer_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the mailer
        profile_name:
          type: string
          minLength: 1
          description: Profile name
        password:
          type: string
          minLength: 1
          description: Password
    connect_imex_request_body:
      title: connect_imex_request_body
      type: object
      description: An Imex account information request body
      required:
        - nickname
        - username
        - password
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        username:
          type: string
          minLength: 1
          description: Username
        password:
          type: string
          minLength: 1
          description: Password
    connect_lasership_request_body:
      title: connect_lasership_request_body
      type: object
      description: A Lasership account information request body
      required:
        - nickname
        - web_services_id
        - web_services_key
        - customer_branch
        - Address
        - PostalCode
        - City
        - State
        - lasership_critical_pull_time
        - lasership_critical_entry_time
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        web_services_id:
          type: string
          minLength: 1
          description: Web Service ID (WSID)
        web_services_key:
          type: string
          minLength: 1
          description: Web Service Key (WSKey)
        customer_branch:
          type: string
          minLength: 1
          description: Customer Branch
        Address:
          type: string
          description: Address
        Address2:
          type: string
          description: Address2
        PostalCode:
          type: string
          description: PostalCode
        City:
          type: string
          description: City
        State:
          type: string
          description: State
        country:
          type: string
          description: Country
        Phone:
          type: string
          description: Phone
        Email:
          type: string
          description: Email
        instructions:
          type: string
          description: Instructions
        facility_code:
          type: string
          description: Facility Code
        lasership_critical_pull_time:
          type: string
          description: Critical Pull Time (local time)
        lasership_critical_entry_time:
          type: string
          description: Critical Entry Time (local time)
        declare_piece_attributes_separately_for_every_shipment:
          type: boolean
          description: >-
            Declare piece attributes separately for every shipment, overrides
            individual attribute below.
          default: false
        AttrAlcohol:
          type: boolean
          description: Set this to true if your shipments will always contain Alcohol
        AttrDryIce:
          type: boolean
          description: Set this to true if your shipments will always contain DryIce
        AttrHazmat:
          type: boolean
          description: Set this to true if your shipments will always contain Hazmat
        AttrTwoPersons:
          type: boolean
          description: Set this to true if your shipments will always require Two Persons
        AttrExplosive:
          type: boolean
          description: Set this to true if your shipments will always contain Explosives
        AttrControlledSubstance:
          type: boolean
          description: >-
            Set this to true if your shipments will always contain Controlled
            Substances
        AttrRefrigerated:
          type: boolean
          description: Set this to true if your shipments will always require Refrigeration
        AttrPerishable:
          type: boolean
          description: Set this to true if your shipments will always be Perishable
        AttrNoRTS:
          type: boolean
          description: >-
            Set this to true if your shipments will always use "No Return To
            Sender"
    connect_newgistics_request_body:
      title: connect_newgistics_request_body
      type: object
      description: A Newgistics account information request body
      required:
        - induction_site
        - nickname
      additionalProperties: false
      properties:
        merchant_id:
          type: integer
          format: int32
          minimum: 0
          description: Merchant id
        mailer_id:
          type: integer
          format: int32
          minimum: 0
          description: Mailer id
        induction_site:
          type: string
          minLength: 1
          description: Induction site
        nickname:
          type: string
          minLength: 1
          description: Nickname
    connect_ontrac_request_body:
      title: connect_ontrac_request_body
      type: object
      description: An Ontrac account information request body
      required:
        - nickname
        - account_number
        - password
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        account_number:
          type: string
          minLength: 1
          description: Account number
        password:
          type: string
          minLength: 1
          description: Password
    connect_purolator_request_body:
      title: connect_purolator_request_body
      type: object
      description: A Purolator account information request body
      required:
        - account_number
        - activation_key
        - nickname
      additionalProperties: false
      properties:
        account_number:
          type: string
          minLength: 1
          description: Account number
        activation_key:
          type: string
          minLength: 1
          description: Activation key
        nickname:
          type: string
          minLength: 1
          description: Nickname
    connect_royal_mail_request_body:
      title: connect_royal_mail_request_body
      type: object
      description: A Royal Mail account information request body
      required:
        - account_number
        - contact_name
        - city
        - postal_code
        - nickname
      additionalProperties: false
      properties:
        account_number:
          type: string
          minLength: 1
          description: Account number
        oba_email:
          allOf:
            - $ref: '#/components/schemas/email'
          description: The oba email address
        contact_name:
          type: string
          minLength: 1
          description: Contact name
        email:
          allOf:
            - $ref: '#/components/schemas/email'
          description: The email address
        company_name:
          type: string
          minLength: 1
          description: Company name
        street_line1:
          type: string
          minLength: 1
          description: Street line1
        street_line2:
          type: string
          minLength: 1
          description: Street line2
        street_line3:
          type: string
          minLength: 1
          description: Street line3
        city:
          type: string
          minLength: 1
          description: City
        postal_code:
          type: string
          minLength: 1
          description: Postal code
        phone:
          type: string
          minLength: 1
          description: Phone
        nickname:
          type: string
          minLength: 1
          description: Nickname
    connect_rr_donnelley_request_body:
      title: connect_rr_donnelley_request_body
      type: object
      description: A RR Donnelley account information request body
      required:
        - nickname
        - username
        - password
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        username:
          type: string
          minLength: 1
          description: Username
        password:
          type: string
          minLength: 1
          description: Password
    connect_seko_request_body:
      title: connect_seko_request_body
      type: object
      description: A SEKO account information request body
      required:
        - nickname
        - access_key
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        access_key:
          type: string
          minLength: 1
          description: Seko Account Access Key
    connect_sendle_request_body:
      title: connect_sendle_request_body
      type: object
      description: A Sendle account information request body
      required:
        - nickname
        - sendle_id
        - api_key
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        sendle_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the sendle
        api_key:
          type: string
          minLength: 1
          description: API key
    connect_stamps_request_body:
      title: connect_stamps_request_body
      type: object
      description: A Stamps account information request body
      required:
        - nickname
        - username
        - password
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        username:
          type: string
          minLength: 1
          description: Username
        password:
          type: string
          minLength: 1
          description: Password
    connect_ups_request_body:
      title: connect_ups_request_body
      type: object
      description: >-
        A UPS account information request body.  The location header from this
        call should be used to redirect to UPS for sign in.
      required:
        - nickname
        - account_number
        - account_postal_code
        - account_country_code
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        account_number:
          type: string
          minLength: 1
          description: Account number
        account_postal_code:
          type: string
          minLength: 1
          description: Account Postal Code
        account_country_code:
          type: string
          minLength: 1
          description: Account Country Code
    connect_carrier_response_body:
      title: connect_carrier_response_body
      type: object
      description: A connect account response body
      required:
        - carrier_id
      additionalProperties: false
      properties:
        carrier_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the carrier
    carrier_name_with_settings:
      title: carrier_name_with_settings
      type: string
      enum:
        - dhl_express
        - fedex
        - newgistics
        - ups
      description: The shipping carriers for which ShipEngine supports carrier settings
    get_carrier_settings_response_body:
      title: get_carrier_settings_response_body
      oneOf:
        - $ref: '#/components/schemas/dhl_express_settings_response_body'
        - $ref: '#/components/schemas/fedex_settings_response_body'
        - $ref: '#/components/schemas/ups_settings_response_body'
    dhl_express_settings_response_body:
      title: dhl_express_settings_response_body
      description: A DHL Express response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/dhl_express_account_settings'
    dhl_express_account_settings:
      title: dhl_express_account_settings
      type: object
      description: A DHL Express account settings
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Account nickname
        should_hide_account_number_on_archive_doc:
          type: boolean
          description: >-
            Indicates if the account number should be hidden on the archive
            documentation
        is_primary_account:
          type: boolean
          description: Indicates if this is primary account
    fedex_settings_response_body:
      title: fedex_settings_response_body
      description: A Fedex settings response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/fedex_account_settings_request_body'
    fedex_account_settings_request_body:
      title: fedex_account_settings_request_body
      description: A Fedex account settings request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/fedex_account_settings'
    fedex_account_settings:
      title: fedex_account_settings
      type: object
      description: A Fedex account settings request body
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Account nickname
        pickup_type:
          allOf:
            - $ref: '#/components/schemas/fedex_pickup_type'
        smart_post_hub:
          allOf:
            - $ref: '#/components/schemas/smart_post_hub'
        smart_post_endorsement:
          allOf:
            - $ref: '#/components/schemas/ancillary_service_endorsement'
        is_primary_account:
          type: boolean
        signature_image:
          type: string
        letterhead_image:
          type: string
    fedex_pickup_type:
      title: fedex_pickup_type
      type: string
      enum:
        - none
        - regular_pickup
        - request_courier
        - drop_box
        - business_service_center
        - station
      description: >
        Tax identifier type for customs declaration


        |Pickup Type               |Description

        |--------------------------|-----------------------------------------

        |`none`                    | Not specified

        |`regular_pickup`          | You already have a daily pickup scheduled
        with FedEx

        |`request_courier`         | You will call FedEx to request a courier

        |`drop_box`                | You will drop-off packages in a FedEx drop
        box

        |`business_service_center` | You will drop-off packages at an authorized
        FedEx business service center

        |`station`                 | You will drop-off the package at a FedEx
        Station
    smart_post_hub:
      title: smart_post_hub
      type: string
      enum:
        - none
        - allentown_pa
        - atlanta_ga
        - baltimore_md
        - charlotte_nc
        - chino_ca
        - dallas_tx
        - denver_co
        - detroit_mi
        - edison_nj
        - grove_city_oh
        - groveport_oh
        - houston_tx
        - indianapolis_in
        - kansas_city_ks
        - los_angeles_ca
        - martinsburg_wv
        - memphis_tn
        - minneapolis_mn
        - new_berlin_wi
        - northborough_ma
        - orlando_fl
        - phoneix_az
        - pittsburgh_pa
        - reno_nv
        - sacramento_ca
        - salt_lake_city_ut
        - seattle_wa
        - st_louis_mo
        - windsor_ct
        - newark_ny
        - south_brunswick_nj
        - scranton_pa
        - wheeling_il
        - middletown_ct
        - portland_or
      description: The possible smart post hub values
    ups_settings_response_body:
      title: ups_settings_response_body
      description: A UPS settings response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/ups_account_settings'
    ups_account_settings:
      title: ups_account_settings
      type: object
      description: UPS account settings
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: nickname
        is_primary_account:
          type: boolean
          description: Indicates if this is the primary UPS account
        pickup_type:
          allOf:
            - $ref: '#/components/schemas/ups_pickup_type'
        use_carbon_neutral_shipping_program:
          type: boolean
          description: The use carbon neutral shipping program
        use_ground_freight_pricing:
          type: boolean
          description: The use ground freight pricing
        use_consolidation_services:
          type: boolean
          description: The use consolidation services
        use_order_number_on_mail_innovations_labels:
          type: boolean
          description: The use order number on mail innovations labels
        mail_innovations_endorsement:
          allOf:
            - $ref: '#/components/schemas/ancillary_service_endorsement'
        mail_innovations_cost_center:
          type: string
          minLength: 0
          description: mail innovations cost center
        use_negotiated_rates:
          type: boolean
          description: The use negotiated rates
        account_postal_code:
          type: string
          minLength: 5
          description: account postal code
        invoice:
          allOf:
            - $ref: '#/components/schemas/ups_invoice'
          description: The invoice
    ups_pickup_type:
      title: ups_pickup_type
      type: string
      enum:
        - daily_pickup
        - occasional_pickup
        - customer_counter
      description: The possible ups pickup type values
    ups_invoice:
      title: ups_invoice
      type: object
      description: UPS invoice
      additionalProperties: false
      properties:
        invoice_date:
          type: string
          format: date-time
          minLength: 1
          description: invoice date
        invoice_number:
          type: string
          minLength: 1
          description: invoice number
        control_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the control
        invoice_amount:
          type: number
          minimum: 0
        invoice_currency_code:
          type: string
    update_carrier_settings_request_body:
      title: update_carrier_settings_request_body
      oneOf:
        - $ref: '#/components/schemas/update_dhl_express_settings_request_body'
        - $ref: '#/components/schemas/update_fedex_settings_request_body'
        - $ref: '#/components/schemas/update_newgistics_settings_request_body'
        - $ref: '#/components/schemas/update_ups_settings_request_body'
        - $ref: '#/components/schemas/update_amazon_buy_shipping_request_body'
    update_dhl_express_settings_request_body:
      title: update_dhl_express_settings_request_body
      description: An update dhl express settings request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/dhl_express_account_settings'
    update_fedex_settings_request_body:
      title: update_fedex_settings_request_body
      description: An update Fedex settings request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/fedex_account_settings'
    update_newgistics_settings_request_body:
      title: update_newgistics_settings_request_body
      type: object
      description: A newgistics account settings request body
      additionalProperties: false
      properties:
        include_barcode_with_order_number:
          type: boolean
        receive_email_on_manifest_processing:
          type: boolean
    update_ups_settings_request_body:
      title: update_ups_settings_request_body
      description: An update UPS settings request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/ups_account_settings'
    update_amazon_buy_shipping_request_body:
      title: update_amazon_buy_shipping_request_body
      type: object
      description: An amazon buy shipping account settings request body
      additionalProperties: false
      properties:
        email:
          type: string
          minLength: 1
          description: Email
    disconnect_insurer_response_body:
      title: disconnect_insurer_response_body
      type: object
    connect_insurer_request_body:
      title: connect_insurer_request_body
      type: object
      description: A create shipsurance connection request body
      required:
        - email
        - policy_id
      additionalProperties: false
      properties:
        email:
          allOf:
            - $ref: '#/components/schemas/email'
        policy_id:
          type: string
          minLength: 1
    connect_insurer_response_body:
      title: connect_insurer_response_body
      type: object
    create_combined_label_document_request_body:
      title: create_combined_label_document_request_body
      type: object
      description: A create combined label document request body
      additionalProperties: false
      properties:
        label_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
          description: >
            The list of up to 30 label ids to include in the combined label
            document.

            Note that to avoid response size limits, you should only expect to
            be able to combine 30 single page labels similar in size to that of
            USPS labels.
        label_format:
          enum:
            - pdf
          type: string
          description: >-
            The file format for the combined label document; note that currently
            only `"pdf"` is supported.
        label_download_type:
          default: inline
          allOf:
            - $ref: '#/components/schemas/label_download_type'
    document_type:
      title: document_type
      type: string
      description: >
        The type of carrier document being registered. Supported values vary by
        carrier. See the [Carrier Document Upload
        guide](/apis/@shipengine/docs/labels/carrier-document-upload.md) for the
        document types each carrier accepts.
      enum:
        - commercial_invoice
        - certificate_of_origin
        - usmca_commercial_invoice_certification_of_origin
        - usmca_certification_of_origin
        - pro_forma_invoice
        - other
        - authorization_form
        - export_accompanying_document
        - export_license
        - import_permit
        - one_time_nafta
        - power_of_attorney
        - packing_list
        - sed_document
        - shippers_letter_of_instruction
        - declaration
        - section_232_customs_affidavit
      example: usmca_commercial_invoice_certification_of_origin
    document_format:
      title: document_format
      type: string
      description: The file format of the document being uploaded.
      enum:
        - PDF
        - PNG
      example: PDF
    document_status_value:
      title: document_status_value
      type: string
      description: >
        The processing status of a carrier document.


        - `awaiting_upload` - The document has been registered and is waiting
        for the file to be uploaded to the provided upload target.

        - `processing` - The uploaded file is being processed.

        - `processing_claimed` - The document has been claimed for processing.

        - `invalid` - The document failed validation and cannot be used.

        - `uploaded` - The file has been uploaded successfully and is ready to
        be sent to the carrier.

        - `queued` - The document is queued to be sent to the carrier.

        - `sent` - The document has been transmitted to the carrier.

        - `failed` - Sending the document to the carrier failed.
      enum:
        - awaiting_upload
        - processing
        - processing_claimed
        - invalid
        - uploaded
        - queued
        - sent
        - failed
      example: awaiting_upload
    register_document_request_body:
      title: register_document_request_body
      type: object
      description: A request to register a carrier document against a shipment or label.
      additionalProperties: false
      required:
        - type
        - file_name
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/document_type'
          description: The type of document being registered.
        format:
          allOf:
            - $ref: '#/components/schemas/document_format'
          description: The file format of the document. Defaults to `PDF` when omitted.
        file_name:
          type: string
          description: The file name of the document, including its extension.
          example: usmca-certification-of-origin.pdf
    register_document_response_body:
      title: register_document_response_body
      type: object
      description: >
        The result of registering a document. Use the returned `upload` target
        to upload the document file to Amazon S3 before sending it to the
        carrier.
      additionalProperties: false
      properties:
        document_id:
          type: string
          description: The unique identifier assigned to the registered document.
          example: 019eb24e-cd4e-7609-b740-c2324fe93272
        upload:
          allOf:
            - $ref: '#/components/schemas/document_upload_target'
          description: >
            The pre-signed Amazon S3 target the document file must be uploaded
            to.
      example:
        document_id: 019eb24e-cd4e-7609-b740-c2324fe93272
        upload:
          url: https://carrier-doc-upload.s3.amazonaws.com
          fields:
            Content-Type: application/pdf
            key: 019eb24e-cd4e-7609-b740-c2324fe93272.pdf
            x-amz-meta-document-id: 019eb24e-cd4e-7609-b740-c2324fe93272
            x-amz-meta-seller-id: '8801990'
            X-Amz-Algorithm: AWS4-HMAC-SHA256
            X-Amz-Credential: ASIA.../20260610/us-east-1/s3/aws4_request
            X-Amz-Date: 20260610T161249Z
            Policy: eyJleHBpcmF0aW9uIjoi...
            X-Amz-Signature: b81189b9df29...
            X-Amz-Security-Token: IQoJb3JpZ2lu...
    document_upload_target:
      title: document_upload_target
      type: object
      description: >
        A pre-signed Amazon S3 POST target describing where and how to upload a
        document file.
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
          description: >
            The Amazon S3 endpoint to upload the document file to via an HTTP
            `POST` with `multipart/form-data`.
          example: https://carrier-doc-upload.s3.amazonaws.com
        fields:
          type: object
          description: >
            The S3 presigned-POST form fields. Include **every** field exactly
            as returned in the upload request, followed by a `file` part
            containing the document content.
          properties:
            Content-Type:
              type: string
              description: >-
                The MIME type of the document; matches the registered document
                format.
              example: application/pdf
            key:
              type: string
              description: The S3 object key the file will be stored under.
              example: 019eb24e-cd4e-7609-b740-c2324fe93272.pdf
            x-amz-meta-document-id:
              type: string
              description: 'S3 object metadata: the registered document''s unique identifier.'
              example: 019eb24e-cd4e-7609-b740-c2324fe93272
            x-amz-meta-seller-id:
              type: string
              description: 'S3 object metadata: the seller''s identifier.'
              example: '8801990'
            X-Amz-Algorithm:
              type: string
              description: The AWS signing algorithm used for the pre-signed POST.
              example: AWS4-HMAC-SHA256
            X-Amz-Credential:
              type: string
              description: The AWS credential scope used to sign the upload.
              example: ASIA.../20260610/us-east-1/s3/aws4_request
            X-Amz-Date:
              type: string
              description: >-
                The timestamp the signature was generated, in ISO 8601 basic
                format.
              example: 20260610T161249Z
            Policy:
              type: string
              description: >
                The base64-encoded S3 POST policy defining the conditions the
                upload must satisfy, such as the allowed key, content type,
                size, and expiration.
              example: eyJleHBpcmF0aW9uIjoi...
            X-Amz-Signature:
              type: string
              description: >-
                The signature authorizing the upload, derived from the policy
                and credentials.
              example: b81189b9df29...
            X-Amz-Security-Token:
              type: string
              description: The temporary AWS session token for the credentials.
              example: IQoJb3JpZ2lu...
          additionalProperties:
            type: string
    document_status:
      title: document_status
      type: object
      description: The current state of a carrier document.
      additionalProperties: false
      properties:
        document_id:
          type: string
          description: The unique identifier of the document.
          example: 7f3c1b2a-9d4e-4f5a-8c6b-2e1d0a9b8c7d
        type:
          allOf:
            - $ref: '#/components/schemas/document_type'
          description: The type of the document.
        file_name:
          type: string
          description: The file name of the document.
          example: usmca-certification-of-origin.pdf
        status:
          allOf:
            - $ref: '#/components/schemas/document_status_value'
          description: The processing status of the document.
        error:
          type: string
          nullable: true
          description: >-
            A description of the error when the document is `invalid` or
            `failed`; otherwise `null`.
          example: The uploaded file could not be read.
        external_id:
          type: string
          nullable: true
          description: >-
            The carrier-assigned identifier for the document once it has been
            sent; otherwise `null`.
          example: 1Z999AA10123456784
    list_documents_response_body:
      title: list_documents_response_body
      type: array
      description: The list of documents registered against the shipment or label.
      items:
        $ref: '#/components/schemas/document_status'
    order_shipment:
      title: order_shipment
      type: object
      description: >-
        A shipment associated with the requested id, along with its registered
        documents.
      additionalProperties: false
      properties:
        shipment_id:
          type: string
          description: The unique identifier of the shipment.
          example: se-28529731
        tracking_number:
          type: string
          description: The tracking number of the shipment.
          example: 1Z999AA10123456784
        documents:
          type: array
          description: The carrier documents registered against the shipment.
          items:
            $ref: '#/components/schemas/document_status'
    list_shipment_labels_response_body:
      title: list_shipment_labels_response_body
      type: array
      description: >-
        The list of shipments associated with the requested id and their
        registered documents.
      items:
        $ref: '#/components/schemas/order_shipment'
    send_documents_response_body:
      title: send_documents_response_body
      type: object
      description: The result of sending a label's documents to the carrier.
      additionalProperties: false
      properties:
        sent_count:
          type: integer
          description: The number of documents that were sent to the carrier.
          example: 2
        document_ids:
          type: array
          items:
            type: string
          description: The identifiers of the documents that were sent.
    label_download_type:
      title: label_download_type
      type: string
      enum:
        - url
        - inline
      description: >
        There are two different ways to download a label:


        |Label Download Type | Description

        |--------------------|------------------------------

        |`url`               |You will receive a URL, which you can use to
        download the label in a separate request. The URL will remain valid for
        90 days.

        |`inline`            |You will receive the Base64-encoded label as part
        of the response. No need for a second request to download the label.
    create_combined_label_document_response_body.yaml:
      title: create_combined_label_document_response_body.yaml
      type: object
      description: A create combined label document response body
      additionalProperties: false
      properties:
        label_download:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/label_download'
          description: The download for the combined label document
    download_file_pdf_response_body:
      title: download_file_pdf_response_body
      type: string
      format: binary
    download_file_png_response_body:
      title: download_file_png_response_body
      type: string
      format: binary
    download_file_zpl_response_body:
      title: download_file_zpl_response_body
      type: string
      format: binary
    list_webhooks_response_body:
      title: list_webhooks_response_body
      type: array
      description: A webhook list response body
      items:
        allOf:
          - $ref: '#/components/schemas/webhook'
        description: The webhook list response body
    webhook:
      title: webhook
      type: object
      description: A webhook
      additionalProperties: false
      properties:
        webhook_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the webhook
        url:
          allOf:
            - $ref: '#/components/schemas/url'
          example: https://example.com/station/events
          description: >-
            The webhook payload listener URL that you intend to target for
            webhook dispatches
        event:
          allOf:
            - $ref: '#/components/schemas/webhook_event'
        headers:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/webhook_header'
          description: Array of custom webhook headers
        name:
          type: string
          example: My Webhook
          description: The name of the webhook
        store_id:
          type: integer
          format: int32
          example: 123456
          description: Store ID
    webhook_event:
      title: webhook_event
      type: string
      enum:
        - batch
        - carrier_connected
        - order_source_refresh_complete
        - rate
        - report_complete
        - sales_orders_imported
        - track
      description: The possible webhook event values
    webhook_header:
      title: webhook_header
      type: object
      description: Optional header to be specified in webhook
      properties:
        key:
          $ref: '#/components/schemas/key'
        value:
          $ref: '#/components/schemas/value'
      required:
        - key
        - value
    key:
      title: key
      type: string
      minLength: 1
      description: Key/name of a header
      example: custom-key
    value:
      title: value
      type: string
      description: Value of a header
      example: custom-value
    create_webhook_request_body:
      title: create_webhook_request_body
      type: object
      description: A create webhook request body
      required:
        - event
        - url
      additionalProperties: false
      properties:
        event:
          allOf:
            - $ref: '#/components/schemas/webhook_event'
        url:
          allOf:
            - $ref: '#/components/schemas/url'
          example: https://example.com/station/events
          description: >-
            The webhook payload listener URL that you intend to target for
            webhook dispatches
        headers:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/webhook_header'
          description: Array of custom webhook headers
        name:
          type: string
          example: My New Webhook
          description: The name of the webhook
        store_id:
          type: integer
          format: int32
          example: 123456
          description: Store ID
    create_webhook_response_body:
      title: create_webhook_response_body
      description: A webhook response body
      additionalProperties: false
      required:
        - webhook_id
        - url
        - event
      allOf:
        - $ref: '#/components/schemas/webhook'
    get_webhook_by_id_response_body:
      title: get_webhook_by_id_response_body
      description: A get webhook id response body
      additionalProperties: false
      required:
        - webhook_id
        - url
        - event
      allOf:
        - $ref: '#/components/schemas/webhook'
    update_webhook_request_body:
      title: update_webhook_request_body
      type: object
      description: An update webhook request body
      additionalProperties: false
      properties:
        url:
          allOf:
            - $ref: '#/components/schemas/url'
          example: https://example.com/station/events
          description: >-
            The webhook payload listener URL that you intend to target for
            webhook dispatches
        headers:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/webhook_header'
          description: Array of custom webhook headers
        name:
          type: string
          example: My Updated Webhook
          description: The name of the webhook
        store_id:
          type: integer
          format: int32
          example: 123456
          description: Store ID
    add_funds_to_insurance_request_body:
      title: add_funds_to_insurance_request_body
      description: An add funds to insurance request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/monetary_value'
    add_funds_to_insurance_response_body:
      title: add_funds_to_insurance_response_body
      description: Add funds to insurance response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/monetary_value'
    get_insurance_balance_response_body:
      title: get_insurance_balance_response_body
      description: A get insurance balance response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/monetary_value'
    label_status:
      title: label_status
      type: string
      enum:
        - processing
        - completed
        - error
        - voided
      description: >
        The possible statuses that a shipping label can be in.


        |Status       |Description

        |:------------|:-----------------------------------------------------

        |`processing` |When labels are created in a batch, it may take a few
        minutes for all of the labels in the batch to be created. During this
        period, they will be in `processing` status.

        |`completed`  |The label was successfully created

        |`error`      |The label could not be created due to an error, such as
        an invalid delivery address

        |`voided`     |The label has been voided
    service_code:
      title: service_code
      type: string
      pattern: ^[a-z0-9]+(_[a-z0-9-]+)* ?$
      example: usps_first_class_mail
      description: >
        A carrier service, such as `fedex_ground`, `usps_first_class_mail`,
        `flat_rate_envelope`, etc.
    list_labels_response_body:
      title: list_labels_response_body
      description: A list label response body
      required:
        - labels
      additionalProperties: false
      properties:
        labels:
          type: array
          minItems: 0
          description: >
            The labels that matched the query criteria.  If no matching labels
            were found, then this array is empty; otherwise, it contains one
            page of results.  The last page of results may have fewer labels
            than the `page_size`.
          items:
            title: label
            type: object
            description: >
              A label represents the physical sticker that you affix to a
              package to ship it.  ShipEngine makes it easy for you to create
              labels and then download them in PDF, PNG, or ZPL format so you
              can print them.
            additionalProperties: false
            properties:
              label_id:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/se_id'
                description: >
                  A string that uniquely identifies the label. This ID is
                  generated by ShipEngine when the label is created.
              status:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/label_status'
              shipment_id:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/se_id'
                description: >
                  The shipment that this label is for.  ShipEngine can create a
                  shipment for you automatically when you create a label, or you
                  can create your own shipment and then use it to print a label
              external_shipment_id:
                readOnly: true
                type: string
                maxLength: 50
                nullable: true
                description: >
                  A unique user-defined key to identify a shipment.  This can be
                  used to retrieve the shipment.
              external_order_id:
                readOnly: true
                type: string
                nullable: true
                description: ID that the Order Source assigned
              shipment:
                writeOnly: true
                allOf:
                  - $ref: '#/components/schemas/shipment'
                description: The shipment information used to generate the label
              ship_date:
                allOf:
                  - $ref: '#/components/schemas/date'
                readOnly: true
                description: >
                  The date that the package was (or will be) shipped. ShipEngine
                  will take the day of week into consideration. For example, if
                  the carrier does not operate on Sundays, then a package that
                  would have shipped on Sunday will ship on Monday instead.
              created_at:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/date_time'
                description: The date and time that the label was created in ShipEngine.
              shipment_cost:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/monetary_value'
                description: >
                  The cost of shipping, delivery confirmation, and other carrier
                  charges.  This amount **does not** include insurance costs.
              insurance_cost:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/monetary_value'
                description: >
                  The insurance cost for this package.  Add this to the
                  `shipment_cost` field to get the total cost.
              requested_comparison_amount:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/monetary_value'
                description: >
                  The total shipping cost for the specified
                  comparison_rate_type.
              rate_details:
                readOnly: true
                description: >
                  A list of rate details that are associated with shipping cost.
                  This is useful for

                  displaying a breakdown of the rate to the user.
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/rate_detail'
              tracking_number:
                type: string
                minLength: 1
                readOnly: true
                example: '782758401696'
                description: >-
                  The tracking number for the package. Tracking number formats
                  vary across carriers.
              is_return_label:
                type: boolean
                description: >
                  Indicates whether this is a return label.  You may also want
                  to set the `rma_number` so you know what is being returned.
              rma_number:
                type: string
                nullable: true
                description: >
                  An optional Return Merchandise Authorization number.  This
                  field is useful for return labels.  You can set it to any
                  string value.
              is_international:
                type: boolean
                readOnly: true
                description: >
                  Indicates whether this is an international shipment.  That is,
                  the originating country and destination country are different.
              batch_id:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/se_id'
                description: >
                  If this label was created as part of a batch, then this is the
                  unique ID of that batch.
              carrier_id:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/se_id'
                description: >
                  The unique ID of the carrier account that was used to create
                  this label
              charge_event:
                allOf:
                  - $ref: '#/components/schemas/label_charge_event'
                description: |
                  The label charge event.
              outbound_label_id:
                allOf:
                  - $ref: '#/components/schemas/se_id'
                writeOnly: true
                description: >
                  The `label_id` of the original (outgoing) label that the
                  return label is for. This associates the two labels together,
                  which is

                  required by some carriers.
              service_code:
                allOf:
                  - $ref: '#/components/schemas/service_code'
                readOnly: true
                description: >
                  The carrier service used to ship the package, such as
                  `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`,
                  etc.
              test_label:
                writeOnly: true
                type: boolean
                default: false
                deprecated: true
                description: >-
                  Indicate if this label is being used only for testing
                  purposes. If true, then no charge will be added to your
                  account.
              package_code:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/package_code'
                description: >
                  The package type, such as `thick_envelope`,
                  `small_flat_rate_box`, `large_package`, etc.  The code
                  `package` indicates a custom or unknown package type.
              validate_address:
                writeOnly: true
                default: validate_and_clean
                allOf:
                  - $ref: '#/components/schemas/validate_address'
              voided:
                type: boolean
                readOnly: true
                description: |
                  Indicates whether the label has been voided
              voided_at:
                type: string
                nullable: true
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/date_time'
                description: >
                  The date and time that the label was voided, or `null` if the
                  label has not been voided
              label_download_type:
                writeOnly: true
                default: url
                allOf:
                  - $ref: '#/components/schemas/label_download_type'
              label_format:
                default: pdf
                allOf:
                  - $ref: '#/components/schemas/label_format'
                description: >
                  The file format that you want the label to be in.  We
                  recommend `pdf` format because it is supported by all
                  carriers, whereas some carriers do not support the `png` or
                  `zpl` formats.
              display_scheme:
                default: label
                allOf:
                  - $ref: '#/components/schemas/display_scheme'
                description: The display format that the label should be shown in.
              label_layout:
                default: 4x6
                allOf:
                  - $ref: '#/components/schemas/label_layout'
                description: >
                  The layout (size) that you want the label to be in.  The
                  `label_format` determines which sizes are allowed.  `4x6` is
                  supported for all label formats, whereas `letter` (8.5" x 11")
                  is only supported for `pdf` format.
              trackable:
                type: boolean
                readOnly: true
                description: >
                  Indicates whether the shipment is trackable, in which case the
                  `tracking_status` field will reflect the current status and
                  each package will have a `tracking_number`.
              label_image_id:
                type: string
                nullable: true
                allOf:
                  - $ref: '#/components/schemas/image_id'
                description: >-
                  The label image resource that was used to create a custom
                  label image.
              carrier_code:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/carrier_code'
                description: >
                  The shipping carrier who will ship the package, such as
                  `fedex`, `dhl_express`, `stamps_com`, etc.
              tracking_status:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/tracking_status'
                description: >-
                  The current status of the package, such as `in_transit` or
                  `delivered`
              confirmation:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/delivery_confirmation'
                description: >-
                  The type of delivery confirmation for this shipment. Defaults
                  to 'none' if not specified.
              label_download:
                allOf:
                  - $ref: '#/components/schemas/label_download'
                readOnly: true
              form_download:
                type: object
                readOnly: true
                nullable: true
                allOf:
                  - $ref: '#/components/schemas/link'
                description: >
                  The link to download the customs form (a.k.a. commercial
                  invoice) for this shipment, if any.  Forms are in PDF format.
                  This field is null if the shipment does not require a customs
                  form, or if the carrier does not support it.
              qr_code_download:
                type: object
                readOnly: true
                nullable: true
                allOf:
                  - $ref: '#/components/schemas/optional_link'
                description: The QR code download for the package
              paperless_download:
                type: object
                readOnly: true
                nullable: true
                allOf:
                  - $ref: '#/components/schemas/paperless_download'
                description: >
                  The paperless details which may contain elements like `href`,
                  `instructions` and `handoff_code`.
              insurance_claim:
                type: object
                readOnly: true
                nullable: true
                allOf:
                  - $ref: '#/components/schemas/link'
                description: >
                  The link to submit an insurance claim for the shipment.  This
                  field is null if the shipment is not insured or if the
                  insurance provider does not support online claim submission.
              packages:
                type: array
                readOnly: true
                description: >
                  The label's package(s).


                  > **Note:** Some carriers only allow one package per label. If
                  you attempt to create a multi-package label for a carrier that
                  doesn't allow it, an error will be returned.
                items:
                  allOf:
                    - $ref: '#/components/schemas/label_package'
                    - $ref: '#/components/schemas/alternative_identifiers'
              alternative_identifiers:
                type: array
                readOnly: true
                nullable: true
                description: >
                  Additional information some carriers may provide by which to
                  identify a given label in their system.
                items:
                  $ref: '#/components/schemas/alternative_identifier'
              tracking_url:
                readOnly: true
                nullable: true
                type: string
                example: >-
                  https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234
                description: >
                  The URL to track the package. This URL is provided by the
                  carrier and is unique to the tracking number.
              ship_to:
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/shipping_address_to'
                description: The recipient's mailing address
      allOf:
        - $ref: '#/components/schemas/paged_list_response_body'
    create_label_request_body:
      title: create_label_request_body
      description: A purchase label request body
      required:
        - shipment
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/label_request'
      properties:
        ship_to_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier service point where the shipment
            will be delivered by the carrier. This will take precedence over a
            shipment's ship to address.
          example: '614940'
        ship_from_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier drop off point where a merchant
            plans to deliver packages. This will take precedence over a
            shipment's ship from address.
          example: '614940'
    create_netstamps_labels_request_body:
      title: create_netstamps_labels_request_body
      type: object
      description: Request body for creating NetStamps labels.
      required:
        - shipments
        - label_layout
      additionalProperties: false
      properties:
        shipments:
          type: array
          minItems: 1
          description: >
            The shipments to create NetStamps labels for. All shipments must use
            the same `carrier_id`.


            Each shipment must include `advanced_options.netstamps_options` with
            `row` and `column` to control stamp placement. Row/column
            combinations must be unique across shipments.
          items:
            $ref: '#/components/schemas/shipment_request'
        label_layout:
          type: string
          description: |
            The NetStamps layout to use.
          example: netstamps_traditional
          enum:
            - netstamps_traditional
            - netstamps_standard
            - netstamps_alternate
            - netstamps_promotional
            - netstamps_themed
            - netstamps_photo_landscape
            - netstamps_photo_portrait
            - netstamps_photo_landscape_hs
            - netstamps_return_address
            - netstamps_roll_type_sd
            - netstamps_promo_paper20
        label_format:
          type: string
          default: pdf
          example: pdf
          enum:
            - pdf
            - png
          description: The file format for the label.
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
        test_label:
          type: boolean
          default: false
          example: true
          description: >-
            Indicate if this label is being used only for testing purposes. If
            true, then no charge will be added to your account.
        label_download_type:
          default: url
          allOf:
            - $ref: '#/components/schemas/label_download_type'
        is_return_label:
          type: boolean
          default: false
          example: true
          description: Indicates whether these are return labels.
        rma_number:
          type: string
          nullable: true
          example: asd12323
          description: >-
            An optional Return Merchandise Authorization number for return
            labels.
        charge_event:
          allOf:
            - $ref: '#/components/schemas/label_charge_event'
          description: The label charge event.
        outbound_label_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The `label_id` of the original label that the return label is for.
        validate_address:
          default: no_validation
          allOf:
            - $ref: '#/components/schemas/validate_address'
        label_image_id:
          allOf:
            - $ref: '#/components/schemas/image_id'
          description: >-
            The label image resource that was used to create a custom label
            image.
        ship_to_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier service point where the shipment
            will be delivered.
          example: '614940'
        ship_from_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier drop off point where a merchant
            plans to deliver packages.
          example: '614940'
    create_mail_labels_request_body:
      title: create_mail_labels_request_body
      type: object
      description: Request body for creating mail labels on a label sheet.
      required:
        - shipments
        - label_layout
        - mailing_options
      additionalProperties: false
      properties:
        shipments:
          type: array
          minItems: 1
          description: >
            The shipments to create mail labels for. All shipments must use the
            same `carrier_id`.
          items:
            $ref: '#/components/schemas/shipment_request'
        mailing_options:
          type: object
          description: >-
            Layout options for printing mail labels on a single sheet. Controls
            the starting position on the label sheet.
          properties:
            start_row:
              type: integer
              format: int32
              minimum: 0
              default: 0
              example: 0
              description: The row on the sheet where label placement begins.
            start_column:
              type: integer
              format: int32
              minimum: 0
              default: 0
              example: 0
              description: The column on the sheet where label placement begins.
        label_layout:
          type: string
          description: |
            The mail label layout to use.
          example: mail_label_sdc3110
          enum:
            - mail_label_sdc3110
            - mail_label_avery5160
            - mail_label_avery5163
        label_format:
          type: string
          default: pdf
          example: pdf
          enum:
            - pdf
            - png
          description: The file format for the label.
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
        test_label:
          type: boolean
          default: false
          example: true
          description: >-
            Indicate if this label is being used only for testing purposes. If
            true, then no charge will be added to your account.
        label_download_type:
          default: url
          allOf:
            - $ref: '#/components/schemas/label_download_type'
        is_return_label:
          type: boolean
          default: false
          example: true
          description: Indicates whether these are return labels.
        rma_number:
          type: string
          nullable: true
          example: asd12323
          description: >-
            An optional Return Merchandise Authorization number for return
            labels.
        charge_event:
          allOf:
            - $ref: '#/components/schemas/label_charge_event'
          description: The label charge event.
        outbound_label_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The `label_id` of the original label that the return label is for.
        validate_address:
          default: no_validation
          allOf:
            - $ref: '#/components/schemas/validate_address'
        label_image_id:
          allOf:
            - $ref: '#/components/schemas/image_id'
          description: >-
            The label image resource that was used to create a custom label
            image.
        ship_to_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier service point where the shipment
            will be delivered.
          example: '614940'
        ship_from_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier drop off point where a merchant
            plans to deliver packages.
          example: '614940'
    create_envelope_label_request_body:
      title: create_envelope_label_request_body
      type: object
      description: Request body for creating an envelope label.
      required:
        - shipment
        - label_layout
      additionalProperties: false
      properties:
        shipment:
          allOf:
            - $ref: '#/components/schemas/shipment_request'
          description: The shipment information used to generate the envelope label.
        label_layout:
          type: string
          description: |
            The envelope layout to use.
          example: envelope_9
          enum:
            - envelope_9
            - envelope_10
            - envelope_11
            - envelope_12
            - envelope_personal
            - envelope_monarch
            - envelope_greeting
            - envelope_invitation
            - envelope_traditional_single
            - envelope_standard_single
            - envelope_themed_single
            - envelope_photo_landscape_single
            - envelope_photo_portrait_single
            - envelope_return_address_single
            - envelope_alternate_single
            - envelope_themed_alt_single
        label_format:
          type: string
          default: pdf
          example: pdf
          enum:
            - pdf
            - png
            - zpl
          description: The file format for the label.
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
        test_label:
          type: boolean
          default: false
          example: true
          description: >-
            Indicate if this label is being used only for testing purposes. If
            true, then no charge will be added to your account.
        label_download_type:
          default: url
          allOf:
            - $ref: '#/components/schemas/label_download_type'
        is_return_label:
          type: boolean
          default: false
          example: true
          description: Indicates whether this is a return label.
        rma_number:
          type: string
          nullable: true
          example: asd12323
          description: >-
            An optional Return Merchandise Authorization number for return
            labels.
        charge_event:
          allOf:
            - $ref: '#/components/schemas/label_charge_event'
          description: The label charge event.
        outbound_label_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The `label_id` of the original label that the return label is for.
        validate_address:
          default: no_validation
          allOf:
            - $ref: '#/components/schemas/validate_address'
        label_image_id:
          allOf:
            - $ref: '#/components/schemas/image_id'
          description: >-
            The label image resource that was used to create a custom label
            image.
        ship_to_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier service point where the shipment
            will be delivered.
          example: '614940'
        ship_from_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier drop off point where a merchant
            plans to deliver packages.
          example: '614940'
    multi_label_response_body:
      title: multi_label_response_body
      type: object
      description: >
        Response containing multiple labels created from a mailing request.
        Extends the standard label with a total cost summary and associated
        labels.
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/label'
        - type: object
          properties:
            total_cost:
              allOf:
                - $ref: '#/components/schemas/monetary_value'
              readOnly: true
              description: The combined cost of all labels in this mailing request.
            associated_labels:
              type: array
              readOnly: true
              description: The individual labels created for each shipment in the request.
              items:
                $ref: '#/components/schemas/create_label_response_body'
    label_request:
      title: label_request
      type: object
      description: >
        A label represents the physical sticker that you affix to a package to
        ship it.  ShipEngine makes it easy for you to create labels and then
        download them in PDF, PNG, or ZPL format so you can print them.
      additionalProperties: false
      properties:
        shipment:
          allOf:
            - $ref: '#/components/schemas/shipment_request'
          description: The shipment information used to generate the label
        is_return_label:
          type: boolean
          description: >
            Indicates whether this is a return label.  You may also want to set
            the `rma_number` so you know what is being returned.
        rma_number:
          type: string
          nullable: true
          description: >
            An optional Return Merchandise Authorization number.  This field is
            useful for return labels.  You can set it to any string value.
        charge_event:
          allOf:
            - $ref: '#/components/schemas/label_charge_event'
          description: |
            The label charge event.
        outbound_label_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          writeOnly: true
          description: >
            The `label_id` of the original (outgoing) label that the return
            label is for. This associates the two labels together, which is

            required by some carriers.
        test_label:
          writeOnly: true
          type: boolean
          default: false
          deprecated: true
          description: >-
            Indicate if this label is being used only for testing purposes. If
            true, then no charge will be added to your account.
        validate_address:
          writeOnly: true
          default: no_validation
          allOf:
            - $ref: '#/components/schemas/validate_address'
        label_download_type:
          writeOnly: true
          default: url
          allOf:
            - $ref: '#/components/schemas/label_download_type'
        label_format:
          default: pdf
          allOf:
            - $ref: '#/components/schemas/label_format'
          description: >
            The file format that you want the label to be in.  We recommend
            `pdf` format because it is supported by all carriers, whereas some
            carriers do not support the `png` or `zpl` formats.
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
        label_layout:
          default: 4x6
          allOf:
            - $ref: '#/components/schemas/label_layout'
          description: >
            The layout (size) that you want the label to be in.  The
            `label_format` determines which sizes are allowed.  `4x6` is
            supported for all label formats, whereas `letter` (8.5" x 11") is
            only supported for `pdf` format.
        label_image_id:
          type: string
          nullable: true
          allOf:
            - $ref: '#/components/schemas/image_id'
          description: >-
            The label image resource that was used to create a custom label
            image.
    shipment_request:
      title: shipment_request
      type: object
      description: >
        The information necessary to ship a package, such as the origin, the
        destination, the carrier service, and the package dimensions and weight.


        > **Note:** Either `ship_from` or `warehouse_id` must be set.
      required:
        - carrier_id
        - service_code
        - ship_to
        - packages
      additionalProperties: false
      properties:
        carrier_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The carrier account that is billed for the shipping charges
        service_code:
          allOf:
            - $ref: '#/components/schemas/service_code'
          description: >
            The carrier service used to ship the package, such as
            `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc.
        external_order_id:
          type: string
          nullable: true
          description: ID that the Order Source assigned
        items:
          type: array
          default: []
          items:
            allOf:
              - $ref: '#/components/schemas/shipment_item'
          description: >
            Describe the packages included in this shipment as related to
            potential metadata that was imported from

            external order sources
        tax_identifiers:
          type: array
          nullable: true
          items:
            allOf:
              - $ref: '#/components/schemas/tax_identifier'
        external_shipment_id:
          type: string
          maxLength: 50
          nullable: true
          description: >
            A unique user-defined key to identify a shipment.  This can be used
            to retrieve the shipment.


            > **Warning:** The `external_shipment_id` is limited to 50
            characters. Any additional characters will be truncated.
        shipment_number:
          type: string
          maxLength: 50
          nullable: true
          description: >
            A non-unique user-defined number used to identify a shipment.  If
            undefined, this will match the external_shipment_id of the shipment.


            > **Warning:** The `shipment_number` is limited to 50 characters.
            Any additional characters will be truncated.
        ship_date:
          allOf:
            - $ref: '#/components/schemas/date'
          description: >
            The date that the shipment was (or will be) shipped.  ShipEngine
            will take the day of week into consideration. For example, if the
            carrier does not operate on Sundays, then a package that would have
            shipped on Sunday will ship on Monday instead.
        ship_to:
          allOf:
            - $ref: '#/components/schemas/shipping_address_to'
          description: The recipient's mailing address
        ship_from:
          allOf:
            - $ref: '#/components/schemas/shipping_address_from'
          description: >
            The shipment's origin address. If you frequently ship from the same
            location, consider creating a warehouse. Then you can simply specify
            the `warehouse_id` rather than the complete address each time.
        warehouse_id:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The warehouse that the shipment is being shipped from. Either
            `warehouse_id` or `ship_from` must be specified.
        return_to:
          allOf:
            - $ref: '#/components/schemas/shipping_address'
          description: >
            The return address for this shipment.  Defaults to the `ship_from`
            address.
        is_return:
          type: boolean
          nullable: true
          default: false
          description: >
            An optional indicator if the shipment is intended to be a return.
            Defaults to false if not provided.
        confirmation:
          default: none
          allOf:
            - $ref: '#/components/schemas/delivery_confirmation'
          description: >-
            The type of delivery confirmation for this shipment. Defaults to
            'none' if not specified.
        customs:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/international_shipment_options'
          description: >
            Customs information for international shipments.


            > **Note:** International shipments (where `ship_from.country_code`
            differs from `ship_to.country_code`) must include either `customs`
            or `advanced_options`.

            >

            > To prepay duties and taxes (DDP / PDT), set
            `customs.terms_of_trade_code` to `ddp`.

            >

            > Please note that the guaranteed prepaid duties and taxes option is
            available only for eligible ShipStation carriers.
        advanced_options:
          allOf:
            - $ref: '#/components/schemas/advanced_shipment_options'
          description: >
            Advanced shipment options.


            > **Note:** International shipments must include either `customs` or
            `advanced_options`.
        insurance_provider:
          default: none
          allOf:
            - $ref: '#/components/schemas/insurance_provider'
          description: >
            The insurance provider to use for any insured packages in the
            shipment.
        order_source_code:
          allOf:
            - $ref: '#/components/schemas/order_source_name'
        packages:
          type: array
          minItems: 1
          items:
            allOf:
              - $ref: '#/components/schemas/package'
          description: >
            The packages in the shipment.


            > **Note:** Some carriers only allow one package per shipment.  If
            you attempt to create a multi-package shipment for a carrier that
            doesn't allow it, an error will be returned.
        comparison_rate_type:
          nullable: true
          type: string
          description: >-
            Calculate a rate for this shipment with the requested carrier using
            a ratecard that differs from the default.  Only supported for UPS
            and USPS.
          example: retail
    shipment_item:
      title: shipment_item
      type: object
      description: A shipment item
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 0
          description: item name
        sales_order_id:
          type: string
          nullable: true
          description: sales order id
        sales_order_item_id:
          type: string
          nullable: true
          description: sales order item id
        quantity:
          type: integer
          format: int32
          minimum: 0
          description: The quantity of this item included in the shipment
        sku:
          type: string
          nullable: true
          description: Item Stock Keeping Unit
        bundle_sku:
          type: string
          nullable: true
          readOnly: true
          description: Item Stock Keeping Unit of the product bundle
        external_order_id:
          type: string
          nullable: true
          description: external order id
        external_order_item_id:
          type: string
          nullable: true
          description: external order item id
        asin:
          type: string
          nullable: true
          minLength: 10
          maxLength: 10
          example: B00005N5PF
          description: Amazon Standard Identification Number
        order_source_code:
          allOf:
            - $ref: '#/components/schemas/order_source_name'
    order_source_name:
      title: order_source_name
      type: string
      enum:
        - amazon_ca
        - amazon_us
        - brightpearl
        - channel_advisor
        - cratejoy
        - ebay
        - etsy
        - jane
        - groupon_goods
        - magento
        - paypal
        - seller_active
        - shopify
        - stitch_labs
        - squarespace
        - three_dcart
        - tophatter
        - walmart
        - woo_commerce
        - volusion
      description: The order sources that are supported by ShipEngine
    tax_identifier:
      title: tax_identifier
      type: object
      description: A tax identifier object
      additionalProperties: false
      required:
        - taxable_entity_type
        - identifier_type
        - issuing_authority
        - value
      properties:
        taxable_entity_type:
          allOf:
            - $ref: '#/components/schemas/taxable_entity_type'
        identifier_type:
          allOf:
            - $ref: '#/components/schemas/identifier_type'
        issuing_authority:
          type: string
          description: >-
            The authority that issued this tax. This must be a valid 2 character
            ISO 3166 Alpha 2 country code.
        value:
          type: string
          description: The value of the identifier
    taxable_entity_type:
      title: taxable_entity_type
      type: string
      enum:
        - shipper
        - recipient
        - ior
      description: >
        The taxable entity type for this tax item. Valid values include the
        following


        |Value       |Description

        |:---------  |:-----------------------------------------------------

        |`shipper`   | The shipper is responsible for this tax.

        |`recipient` | The recipient of the shipment is responsible for this
        tax.

        |`ior`       | The importer of records is responsible for tax.
    identifier_type:
      title: identifier_type
      type: string
      enum:
        - vat
        - eori
        - ssn
        - ein
        - tin
        - ioss
        - pan
        - voec
        - pccc
        - oss
        - passport
        - abn
        - ukims
      description: >
        Tax identifier type for customs declaration


        |Pickup Type    | Description

        |---------------|-----------------------------------------

        |`vat`          | The tax identifier is a Value Added Tax.

        |`eori`         | The tax identifier is an Economic Operators
        Registration and Identification Number (EORI).

        |`ssn`          | The tax identifier is a Social Security Number.

        |`ein`          | The tax identifier is an Employer Identification
        Number (EIN).

        |`tin`          | The tax identifier is a Tax Identification Number
        (TIN).

        |`ioss`         | The tax identifier is an Import One-Stop Shop (IOSS).

        |`pan`          | The tax identifier is a Permanent Account Number
        (PAN).

        |`voec`         | The tax identifier is a Norwegian VAT On
        E-Commerce(VOEC).

        |`pccc`         | The tax identifier is a Personal Customs Clearance
        Code (PCCC).

        |`oss`          | The tax identifier is an One-Stop Shop (OSS).

        |`passport`     | The tax identifier is a Passport Number.

        |`abn`          | The tax identifier is an Australian Business Number.

        |`ukims`        | The tax identifier is an UK Internal Market Scheme
        number.
    date:
      title: date
      type: string
      format: date-time
      pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2}))?$
      example: '2018-09-23T00:00:00.000Z'
      description: >
        An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that
        represents a date, but not a specific time.  The value _may_ contain a
        time component, but it will be set to `00:00:00` UTC by ShipEngine.
    shipping_address_to:
      title: shipping_address_to
      allOf:
        - $ref: '#/components/schemas/address'
        - $ref: '#/components/schemas/partial_shipping_address_to'
    partial_shipping_address_to:
      title: partial_shipping_address_to
      type: object
      description: A complete or partial mailing address.
      properties:
        instructions:
          type: string
          minLength: 1
          nullable: true
          description: |
            Additional text about how to handle the shipment at this address.
        geolocation:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: what3words
                description: |
                  Enum of available type of geolocation items:
                    - 'what3words' functionality allows to specify a location by providing 3 words that have been assigned to the specific location. See [link](https://what3words.com/business) for more details.
                enum:
                  - what3words
              value:
                type: string
                example: cats.with.thumbs
                description: value of the geolocation item
    shipping_address_from:
      title: shipping_address_from
      required:
        - phone
        - country_code
      allOf:
        - $ref: '#/components/schemas/address'
        - $ref: '#/components/schemas/partial_shipping_address'
    partial_shipping_address:
      title: partial_shipping_address
      type: object
      description: A complete or partial mailing address.
      properties:
        instructions:
          type: string
          minLength: 1
          nullable: true
          description: |
            Additional text about how to handle the shipment at this address.
        geolocation:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: what3words
                description: |
                  Enum of available type of geolocation items:
                    - 'what3words' functionality allows to specify a location by providing 3 words that have been assigned to the specific location. See [link](https://what3words.com/business) for more details.
                enum:
                  - what3words
              value:
                type: string
                example: cats.with.thumbs
                description: value of the geolocation item
    shipping_address:
      title: shipping_address
      allOf:
        - $ref: '#/components/schemas/address'
        - $ref: '#/components/schemas/partial_shipping_address'
    delivery_confirmation:
      title: delivery_confirmation
      type: string
      enum:
        - none
        - delivery
        - signature
        - adult_signature
        - adult_signature_restricted_delivery
        - direct_signature
        - delivery_mailed
        - verbal_confirmation
        - delivery_code
        - age_verification_16_plus
      description: The possible delivery confirmation values
    international_shipment_options:
      title: international_shipment_options
      type: object
      description: Options for international shipments, such as customs declarations.
      required:
        - contents
        - non_delivery
      additionalProperties: false
      example:
        terms_of_trade_code: ddp
        contents: gift
        non_delivery: return_to_sender
      properties:
        contents:
          default: merchandise
          allOf:
            - $ref: '#/components/schemas/package_contents'
          description: >-
            The type of contents in this shipment.  This may impact import
            duties or customs treatment.
        contents_explanation:
          type: string
          description: >-
            Explanation for contents (required if the `contents` is provided as
            `other`)
        non_delivery:
          default: return_to_sender
          allOf:
            - $ref: '#/components/schemas/non_delivery'
          description: Indicates what to do if a package is unable to be delivered.
        terms_of_trade_code:
          description: Specifies the supported terms of trade code (incoterms)
          allOf:
            - $ref: '#/components/schemas/allowed_incoterms'
        declaration:
          type: string
          description: Declaration statement to be placed on the commercial invoice
        pending_documents:
          type: boolean
          default: false
          description: >
            Set to `true` to indicate the shipment requires customs documents to
            be uploaded via Carrier Document Upload. See the [Carrier Document
            Upload
            guide](/apis/@shipengine/docs/labels/carrier-document-upload.md).
          example: true
        invoice_additional_details:
          allOf:
            - $ref: '#/components/schemas/invoice_additional_details'
        importer_of_record:
          allOf:
            - $ref: '#/components/schemas/importer_of_records'
        license_number:
          type: string
          description: The license number to be used in the customs.
        certificate_number:
          type: string
          description: The certificate number to be used in the customs.
        customs_items:
          deprecated: true
          type: array
          default: []
          minItems: 0
          description: >-
            Customs declarations for each item in the shipment. (Please provide
            this information under `products` inside `packages`)
          items:
            $ref: '#/components/schemas/customs_item'
    package_contents:
      title: package_contents
      type: string
      enum:
        - merchandise
        - documents
        - gift
        - returned_goods
        - sample
        - e_commerce_goods
        - commercial_sale_of_goods_b2b
        - other
      description: The possible package contents values
    non_delivery:
      title: non_delivery
      type: string
      enum:
        - return_to_sender
        - treat_as_abandoned
      description: The possible non delivery values
    allowed_incoterms:
      title: Allowed incoterms
      type: string
      description: >
        The Incoterms code (terms of trade) for the shipment.


        Set to `ddp` to prepay duties and taxes: indicates that the shipper is
        paying the international delivery duties for this shipment. This option
        is currently supported by UPS, FedEx, and DHL Express.
      enum:
        - exw
        - fca
        - cpt
        - cip
        - dpu
        - dap
        - ddp
        - fas
        - fob
        - cfr
        - cif
        - ddu
        - daf
        - deq
        - des
    invoice_additional_details:
      title: invoice_additional_details
      type: object
      description: |
        The additional information to put on commercial invoice
      properties:
        freight_charge:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: Freight Charge for shipment.
        insurance_charge:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: Insurance Charge for shipment.
        discount:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: Discount for shipment.
        estimated_import_charges:
          allOf:
            - $ref: '#/components/schemas/estimated_import_charges'
          description: >-
            Estimated import charges for commercial invoices for international
            shipments.
        other_charge:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: Other charge for shipment.
        other_charge_description:
          type: string
          description: Description for the other charge (if provided).
        invoice_number:
          type: string
          description: The invoice number to be used in the customs.
    estimated_import_charges:
      title: estimated_import_charges
      type: object
      description: >
        Estimated import charges for commercial invoices for international
        shipments.
      additionalProperties: false
      properties:
        taxes:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: Estimated import taxes.
        duties:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: Estimated import duties.
    importer_of_records:
      title: importer_of_records
      type: object
      description: |
        importer of records address, anywhere in the world.
      required:
        - name
        - address_line1
        - city_locality
        - postal_code
        - country_code
      properties:
        name:
          type: string
          minLength: 1
          example: John Doe
          description: >
            The name of a contact person at this address. Either `name` or the
            `company_name` field should always be set.
        phone:
          type: string
          minLength: 1
          example: +1 204-253-9411 ext. 123
          description: >
            The phone number of a contact person at this address.  The format of
            this phone number varies depending on the country.
        email:
          type: string
          nullable: true
          example: example@example.com
          description: |
            Email for the address owner.
        company_name:
          type: string
          minLength: 1
          nullable: true
          example: The Home Depot
          description: >
            If this is a business address, then the company name should be
            specified here. Either `name` or the `company_name` field should
            always be set.
        address_line1:
          type: string
          minLength: 1
          example: 1999 Bishop Grandin Blvd.
          description: >
            The first line of the street address.  For some addresses, this may
            be the only line.  Other addresses may require 2 or 3 lines.
        address_line2:
          type: string
          minLength: 1
          nullable: true
          example: Unit 408
          description: >
            The second line of the street address.  For some addresses, this
            line may not be needed.
        address_line3:
          type: string
          minLength: 1
          nullable: true
          example: 'Building #7'
          description: >
            The third line of the street address.  For some addresses, this line
            may not be needed.
        city_locality:
          type: string
          minLength: 1
          example: Winnipeg
          description: The name of the city or locality
        state_province:
          type: string
          minLength: 1
          example: Manitoba
          description: >
            The state or province.  For some countries (including the U.S.) only
            abbreviations are allowed.  Other countries allow the full name or
            abbreviation.
        postal_code:
          allOf:
            - $ref: '#/components/schemas/postal_code'
        country_code:
          allOf:
            - $ref: '#/components/schemas/country_code'
          description: >
            The two-letter [ISO 3166-1 country
            code](https://en.wikipedia.org/wiki/ISO_3166-1)
    customs_item:
      title: customs_item
      type: object
      description: The customs declaration for a single item in the shipment.
      required:
        - customs_item_id
      additionalProperties: false
      properties:
        customs_item_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the customs item
        description:
          type: string
          nullable: true
          maxLength: 100
          default: null
          description: A description of the item
        quantity:
          type: integer
          format: int32
          minimum: 0
          default: 0
          description: The quantity of this item in the shipment.
        value:
          type: number
          minimum: 0
          description: The monetary amount, in the specified currency.
        value_currency:
          type: string
          description: >
            The currencies that are supported by ShipEngine are the ones that
            specified by ISO 4217:
            https://www.iso.org/iso-4217-currency-codes.html
        weight:
          allOf:
            - $ref: '#/components/schemas/weight'
          description: The item weight
        harmonized_tariff_code:
          type: string
          nullable: true
          default: null
          example: '3926.1'
          description: >-
            The [Harmonized Tariff
            Code](https://en.wikipedia.org/wiki/Harmonized_System) of this item.
        country_of_origin:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/country_code'
          description: >
            The two-letter [ISO 3166-1 country
            code](https://en.wikipedia.org/wiki/ISO_3166-1) where this item
            originated
        unit_of_measure:
          type: string
          nullable: true
        sku:
          type: string
          description: The SKU (Stock Keeping Unit) of the customs item
          nullable: true
        sku_description:
          type: string
          description: Description of the Custom Item's SKU
          nullable: true
    weight:
      title: weight
      type: object
      description: The weight of a package
      required:
        - value
        - unit
      additionalProperties: false
      properties:
        value:
          type: number
          minimum: 0
          description: The weight, in the specified unit
        unit:
          allOf:
            - $ref: '#/components/schemas/weight_unit'
    weight_unit:
      title: weight_unit
      type: string
      enum:
        - pound
        - ounce
        - gram
        - kilogram
      description: The possible weight unit values
    advanced_shipment_options:
      title: advanced_shipment_options
      type: object
      description: Advanced shipment options
      additionalProperties: true
      properties:
        bill_to_account:
          type: string
          nullable: true
          default: null
          description: >
            This field is used to bill shipping costs to a third party. This
            field must be used in conjunction with the `bill_to_country_code`,
            `bill_to_party`, and `bill_to_postal_code` fields.
        bill_to_country_code:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/country_code'
          description: >
            The two-letter [ISO 3166-1 country
            code](https://en.wikipedia.org/wiki/ISO_3166-1) of the third-party
            that is responsible for shipping costs.
        bill_to_party:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/bill_to_party'
          description: >
            Indicates whether to bill shipping costs to the recipient or to a
            third-party.  When billing to a third-party, the `bill_to_account`,
            `bill_to_country_code`, and `bill_to_postal_code` fields must also
            be set.
        bill_to_postal_code:
          type: string
          nullable: true
          default: null
          description: >
            The postal code of the third-party that is responsible for shipping
            costs.
        contains_alcohol:
          type: boolean
          default: false
          description: Indicates that the shipment contains alcohol.
        delivered_duty_paid:
          type: boolean
          default: false
          description: >
            Indicates that the shipper is paying the international delivery
            duties for this shipment.  This option is supported by UPS, FedEx,
            and DHL Express.
        dry_ice:
          type: boolean
          default: false
          description: Indicates if the shipment contain dry ice
        dry_ice_weight:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/weight'
          description: The weight of the dry ice in the shipment
        non_machinable:
          type: boolean
          default: false
          description: >
            Indicates that the package cannot be processed automatically because
            it is too large or irregularly shaped. This is primarily for USPS
            shipments.  See [Section 1.2 of the USPS parcel
            standards](https://pe.usps.com/text/dmm300/101.htm#ep1047495) for
            details.
        saturday_delivery:
          type: boolean
          default: false
          description: Enables Saturday delivery, if supported by the carrier.
        fedex_freight:
          type: object
          description: Provide details for the Fedex freight service
          properties:
            shipper_load_and_count:
              type: string
            booking_confirmation:
              type: string
        use_ups_ground_freight_pricing:
          type: boolean
          nullable: true
          default: null
          description: >
            Whether to use UPS Ground Freight pricing. If enabled, then a
            `freight_class` must also be specified.
        freight_class:
          type: string
          nullable: true
          default: null
          example: '77.5'
          description: >
            The National Motor Freight Traffic Association [freight
            class](http://www.nmfta.org/pages/nmfc?AspxAutoDetectCookieSupport=1),
            such as "77.5", "110", or "250".
        custom_field1:
          type: string
          nullable: true
          default: null
          maxLength: 100
          description: >
            An arbitrary field that can be used to store information about the
            shipment.
        custom_field2:
          type: string
          nullable: true
          default: null
          maxLength: 100
          description: >
            An arbitrary field that can be used to store information about the
            shipment.
        custom_field3:
          type: string
          nullable: true
          default: null
          maxLength: 100
          description: >
            An arbitrary field that can be used to store information about the
            shipment.
        origin_type:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/origin_type'
        additional_handling:
          type: boolean
          nullable: true
          default: null
          description: >
            Indicate to the carrier that this shipment requires additional
            handling.
        shipper_release:
          type: boolean
          nullable: true
          default: null
        collect_on_delivery:
          $ref: '#/components/schemas/collect_on_delivery'
        third_party_consignee:
          type: boolean
          default: false
          description: >-
            Third Party Consignee option is a value-added service that allows
            the shipper to supply goods without commercial invoices being
            attached
        dangerous_goods:
          type: boolean
          default: false
          description: Indicates if the Dangerous goods are present in the shipment
        dangerous_goods_contact:
          type: object
          description: Contact information for Dangerous goods
          properties:
            name:
              type: string
              description: Name of the contact
            phone:
              type: string
              description: Phone number of the contact
        movement_indicator:
          type: string
          nullable: true
          default: null
          description: >-
            An indicator that will tell the carrier the type of movement for the
            shipment.
          example: c2c
          enum:
            - c2c
            - b2c
            - c2b
            - b2b
        windsor_framework_details:
          type: object
          description: >-
            The Windsor framework is a new regulation in the UK that simplifies
            customs procedures for goods moved from the UK mainland to Northern
            Ireland.
          properties:
            movement_indicator:
              type: string
              deprecated: true
              description: >-
                An indicator that will tell the carrier and HMRC the type of
                movement for the shipment.
              enum:
                - c2c
                - b2c
                - c2b
                - b2b
            not_at_risk:
              type: boolean
              description: >-
                An indicator that allows a shipper to declare the shipment as
                not-at-risk.
        license_number:
          type: string
          nullable: true
          default: null
          example: '514785'
          description: >-
            license_number - This field was part of a historical implementation
            for passing customs-related data. For new integrations, please use
            the corresponding parameters within the shipment.customs object.
        invoice_number:
          type: string
          nullable: true
          default: null
          example: IOC56888
          description: >-
            invoice_number - This field was part of a historical implementation
            for passing customs-related data. For new integrations, please use
            the corresponding parameters within the shipment.customs object.
        certificate_number:
          type: string
          nullable: true
          default: null
          example: '784515'
          description: >-
            certificate_number - This field was part of a historical
            implementation for passing customs-related data. For new
            integrations, please use the corresponding parameters within the
            shipment.customs object.
        fragile:
          type: boolean
          default: false
          example: true
          description: >-
            Indicates that the contents of the package are fragile and should be
            handled with care.
        delivery_as_addressed:
          type: boolean
          default: false
          example: true
          description: >-
            Instructs the carrier to deliver the package only to the exact
            address provided.
        return_after_first_attempt:
          type: boolean
          default: false
          example: true
          description: >-
            Ensures the shipment is immediately flagged for return to the sender
            if the initial delivery attempt fails.
        regulated_content_type:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/regulated_content_type'
          description: >-
            Indicates the category of goods in the shipment that is subject to
            special regulatory or compliance requirements.
        netstamps_options:
          type: object
          description: >-
            Layout options for printing NetStamps labels on a sheet. Controls
            the starting position on the label sheet.
          properties:
            row:
              type: integer
              format: int32
              description: The row on the sheet where label is placed.
              example: 1
            column:
              type: integer
              format: int32
              description: The column on the sheet where label is placed.
              example: 1
    bill_to_party:
      title: bill_to_party
      type: string
      enum:
        - recipient
        - third_party
      description: The possible bill to party values
    origin_type:
      title: origin_type
      type: string
      enum:
        - pickup
        - drop_off
      description: Indicates if the package will be picked up or dropped off by the carrier
    collect_on_delivery:
      title: collect_on_delivery
      type: object
      description: Defer payment until package is delivered, instead of when it is ordered.
      properties:
        payment_type:
          allOf:
            - $ref: '#/components/schemas/collect_on_delivery_payment_type'
        payment_amount:
          $ref: '#/components/schemas/payment_amount'
    collect_on_delivery_payment_type:
      title: collect_on_delivery_payment_type
      type: string
      enum:
        - any
        - cash
        - cash_equivalent
        - none
      description: Types of payment that are supported
    payment_amount:
      title: payment_amount
      type: object
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/currency'
        amount:
          minimum: 0
    regulated_content_type:
      title: regulated_content_type
      type: string
      enum:
        - day_old_poultry
        - other_live_animal
      description: >-
        Indicates the category of goods in the shipment that is subject to
        special regulatory or compliance requirements.
    insurance_provider:
      title: insurance_provider
      type: string
      enum:
        - none
        - shipsurance
        - parcelguard
        - xcover
        - carrier
        - third_party
      description: The possible insurance provider values
    package:
      title: package
      type: object
      description: |
        A package associated with a shipment
      required:
        - weight
      additionalProperties: false
      properties:
        shipment_package_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          readOnly: true
          description: A string that uniquely identifies this shipment package
        package_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies this package type
        package_code:
          allOf:
            - $ref: '#/components/schemas/package_code'
          description: >
            The package type, such as `thick_envelope`, `small_flat_rate_box`,
            `large_package`, etc.  The code `package` indicates a custom or
            unknown package type.
        package_name:
          type: string
          description: The name of the of the package type
        weight:
          allOf:
            - $ref: '#/components/schemas/weight'
          description: The package weight
        dimensions:
          allOf:
            - $ref: '#/components/schemas/dimensions'
          description: The package dimensions
        insured_value:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          default:
            currency: USD
            amount: 0
          description: >
            The insured value of the package.  Requires the `insurance_provider`
            field of the shipment to be set.
        label_messages:
          allOf:
            - $ref: '#/components/schemas/label_messages'
        external_package_id:
          type: string
          minLength: 1
          description: An external package id.
        content_description:
          type: string
          minLength: 1
          maxLength: 35
          description: >
            A short description of the package content. Required for shipments
            moving to, from, and through Mexico.
          example: Hand knitted wool socks
          nullable: true
        products:
          type: array
          default: []
          minItems: 0
          description: >-
            Details about products inside packages (Information provided would
            be used on custom documentation)
          items:
            $ref: '#/components/schemas/products'
    label_messages:
      title: label_messages
      type: object
      description: >
        Custom messages to print on the shipping label for the package.  These
        are typically used to print invoice numbers, product numbers, or other
        internal reference numbers.  Not all carriers support label messages.
        The number of lines and the maximum length of each line also varies by
        carrier.


        |Carrier            |Max lines |Max line length

        |-------------------|----------|--------------------

        |USPS (Stamps.com)  |3         |60

        |FedEx              |3         |35 for the first line. 30 for additional
        lines.

        |UPS                |2         |35

        |OnTrac             |2         |25
      required:
        - reference1
        - reference2
        - reference3
      additionalProperties: false
      properties:
        reference1:
          type: string
          nullable: true
          default: null
          description: >
            The first line of the custom label message.  Some carriers may
            prefix this line with something like "REF", "Reference", "Trx Ref
            No.", etc.
        reference2:
          type: string
          nullable: true
          default: null
          description: >
            The second line of the custom label message.  Some carriers may
            prefix this line with something like "INV", "Reference 2", "Trx Ref
            No.", etc.
        reference3:
          type: string
          nullable: true
          default: null
          description: >
            The third line of the custom label message.  Some carriers may
            prefix this line with something like "PO", "Reference 3", etc.
    tracking_number:
      title: tracking_number
      type: string
      minLength: 1
      example: 1Z932R800392060079
      description: A tracking number for a package. The format depends on the carrier.
    products:
      title: products
      type: object
      description: The customs declaration for a single item in the shipment.
      additionalProperties: false
      properties:
        description:
          type: string
          nullable: true
          maxLength: 100
          default: null
          description: A description of the item
        quantity:
          type: integer
          format: int32
          minimum: 0
          default: 0
          description: The quantity of this item in the shipment.
        value:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The declared value of each item
        weight:
          allOf:
            - $ref: '#/components/schemas/weight'
          description: The item weight
        harmonized_tariff_code:
          type: string
          nullable: true
          default: null
          example: '3926.1'
          description: >-
            The [Harmonized Tariff
            Code](https://en.wikipedia.org/wiki/Harmonized_System) of this item.
        country_of_origin:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/country_code'
          description: >
            The two-letter [ISO 3166-1 country
            code](https://en.wikipedia.org/wiki/ISO_3166-1) where this item
            originated
        unit_of_measure:
          type: string
          nullable: true
        sku:
          type: string
          description: The SKU (Stock Keeping Unit) of the item
          nullable: true
        sku_description:
          type: string
          description: Description of the Custom Item's SKU
          nullable: true
        mid_code:
          type: string
          description: Manufacturers Identification code
          nullable: true
        product_url:
          type: string
          description: link to the item on the seller website
          nullable: true
        vat_rate:
          type: number
          description: VAT rate applicable to the item
          nullable: true
          example: 0.2
        dangerous_goods:
          type: array
          default: []
          minItems: 0
          description: Details about dangerous goods inside products
          items:
            $ref: '#/components/schemas/dangerous_goods'
        manufacturer_product_id_type:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/manufacturer_product_identifier_type'
          description: The type of identifier used for the manufacturer product ID.
          example: gtin
        manufacturer_product_id:
          type: string
          nullable: true
          default: null
          description: >-
            The manufacturer's product identifier corresponding to the
            `manufacturer_product_id_type`.
          example: '012345678905'
        manufacturer_ns_product_id:
          type: string
          nullable: true
          default: null
          description: >-
            A non-standardized product identifier unique to the manufacturer's
            own system that does not follow an internationally recognized
            standard (e.g. a SKU).
          example: MY-SKU-12345
        cpsc_certificates:
          type: array
          nullable: true
          default: null
          description: List of CPSC eFiling certificates associated with this product.
          items:
            $ref: '#/components/schemas/cpsc_certificate'
        extended_details:
          type: object
          description: Additional details about products
          additionalProperties: true
    dangerous_goods:
      title: dangerous_goods
      type: object
      description: |
        Dangerous goods attribute associated with the product
      additionalProperties: false
      properties:
        id_number:
          type: string
          nullable: true
          default: null
          description: UN number to identify the dangerous goods.
        shipping_name:
          type: string
          nullable: true
          default: null
          description: Trade description of the dangerous goods.
        technical_name:
          type: string
          nullable: true
          default: null
          description: Recognized Technical or chemical name of dangerous goods.
        product_class:
          type: string
          nullable: true
          default: null
          description: Dangerous goods product class based on regulation.
        product_class_subsidiary:
          type: string
          nullable: true
          default: null
          description: >-
            A secondary of product class for substances presenting more than one
            particular hazard
        packaging_group:
          $ref: '#/components/schemas/packaging_group'
        dangerous_amount:
          allOf:
            - $ref: '#/components/schemas/dangerous_amount'
          description: This model represents the amount of the dangerous goods.
        quantity:
          type: integer
          format: int32
          minimum: 0
          default: 0
          description: Quantity of dangerous goods.
        packaging_instruction:
          type: string
          nullable: true
          default: null
          description: >-
            The specific standardized packaging instructions from the relevant
            regulatory agency that have been applied to the parcel/container.
        packaging_instruction_section:
          $ref: '#/components/schemas/packaging_instruction_section'
        packaging_type:
          type: string
          nullable: true
          default: null
          description: The type of exterior packaging used to contain the dangerous good.
        transport_mean:
          $ref: '#/components/schemas/transport_mean'
        transport_category:
          type: string
          nullable: true
          default: null
          description: >-
            Transport category assign to dangerous goods for the transport
            purpose.
        regulation_authority:
          type: string
          nullable: true
          default: null
          description: Name of the regulatory authority.
        regulation_level:
          $ref: '#/components/schemas/regulation_level'
        radioactive:
          type: boolean
          nullable: true
          example: false
          description: Indication if the substance is radioactive.
        reportable_quantity:
          type: boolean
          nullable: true
          example: false
          description: >-
            Indication if the substance needs to be reported to regulatory
            authority based on the quantity.
        tunnel_code:
          type: string
          nullable: true
          default: null
          description: Defines which types of tunnels the shipment is allowed to go through
        additional_description:
          type: string
          nullable: true
          default: null
          description: >-
            Provider additonal description regarding the dangerous goods. This
            is used as a placed holder to provider additional context and varies
            by carrier
    packaging_group:
      title: packaging_group
      type: string
      enum:
        - i
        - ii
        - iii
    dangerous_amount:
      title: dangerous_amount
      type: object
      description: This model represents the amount of the dangerous goods..
      additionalProperties: false
      properties:
        amount:
          type: number
          minimum: 0
          default: 0
          description: The amount of dangerous goods.
        unit:
          type: string
          nullable: true
          default: null
          description: The unit of dangerous goods.
    packaging_instruction_section:
      title: packaging_instruction_section
      type: string
      enum:
        - section_1
        - section_2
        - section_1a
        - section_1b
    transport_mean:
      title: transport_mean
      type: string
      enum:
        - ground
        - water
        - cargo_aircraft_only
        - passenger_aircraft
    regulation_level:
      title: regulation_level
      type: string
      enum:
        - lightly_regulated
        - fully_regulated
        - limited_quantities
        - excepted_quantity
    label_charge_event:
      title: label_charge_event
      type: string
      enum:
        - carrier_default
        - on_creation
        - on_carrier_acceptance
      description: Determines when the user's account will be charged for the label.
    validate_address:
      title: validate_address
      type: string
      enum:
        - no_validation
        - validate_only
        - validate_and_clean
      description: The possible validate address values
    create_label_response_body:
      title: create_label_response_body
      description: A create label response body
      additionalProperties: false
      required:
        - label_id
        - status
        - shipment_id
        - external_shipment_id
        - external_order_id
        - ship_date
        - created_at
        - shipment_cost
        - insurance_cost
        - tracking_number
        - is_international
        - batch_id
        - carrier_id
        - service_code
        - voided
        - label_image_id
        - label_format
        - label_layout
        - trackable
        - carrier_code
        - tracking_status
        - label_download
        - form_download
        - qr_code_download
        - paperless_download
        - insurance_claim
        - packages
        - is_return_label
        - rma_number
        - charge_event
        - package_code
        - display_scheme
        - ship_to
      allOf:
        - $ref: '#/components/schemas/label'
    label:
      title: label
      type: object
      description: >
        A label represents the physical sticker that you affix to a package to
        ship it.  ShipEngine makes it easy for you to create labels and then
        download them in PDF, PNG, or ZPL format so you can print them.
      properties:
        label_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            A string that uniquely identifies the label. This ID is generated by
            ShipEngine when the label is created.
        status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/label_status'
        shipment_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The shipment that this label is for.  ShipEngine can create a
            shipment for you automatically when you create a label, or you can
            create your own shipment and then use it to print a label
        external_shipment_id:
          readOnly: true
          type: string
          maxLength: 50
          nullable: true
          description: >
            A unique user-defined key to identify a shipment.  This can be used
            to retrieve the shipment.
        external_order_id:
          readOnly: true
          type: string
          nullable: true
          description: ID that the Order Source assigned
        shipment:
          writeOnly: true
          allOf:
            - $ref: '#/components/schemas/shipment'
          description: The shipment information used to generate the label
        ship_date:
          allOf:
            - $ref: '#/components/schemas/date'
          readOnly: true
          description: >
            The date that the package was (or will be) shipped.  ShipEngine will
            take the day of week into consideration. For example, if the carrier
            does not operate on Sundays, then a package that would have shipped
            on Sunday will ship on Monday instead.
        created_at:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time that the label was created in ShipEngine.
        shipment_cost:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: >
            The cost of shipping, delivery confirmation, and other carrier
            charges.  This amount **does not** include insurance costs.
        insurance_cost:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: >
            The insurance cost for this package.  Add this to the
            `shipment_cost` field to get the total cost.
        requested_comparison_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: |
            The total shipping cost for the specified comparison_rate_type.
        rate_details:
          readOnly: true
          description: >
            A list of rate details that are associated with shipping cost. This
            is useful for displaying a breakdown of the rate to the user.
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/rate_detail'
        tracking_number:
          type: string
          minLength: 1
          readOnly: true
          example: '782758401696'
          description: >-
            The tracking number for the package. Tracking number formats vary
            across carriers.
        is_return_label:
          type: boolean
          description: >
            Indicates whether this is a return label.  You may also want to set
            the `rma_number` so you know what is being returned.
        rma_number:
          type: string
          nullable: true
          description: >
            An optional Return Merchandise Authorization number.  This field is
            useful for return labels.  You can set it to any string value.
        is_international:
          type: boolean
          readOnly: true
          description: >
            Indicates whether this is an international shipment.  That is, the
            originating country and destination country are different.
        batch_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            If this label was created as part of a batch, then this is the
            unique ID of that batch.
        carrier_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The unique ID of the carrier account that was used to create this
            label
        charge_event:
          allOf:
            - $ref: '#/components/schemas/label_charge_event'
          description: |
            The label charge event.
        outbound_label_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          writeOnly: true
          description: >
            The `label_id` of the original (outgoing) label that the return
            label is for. This associates the two labels together, which is

            required by some carriers.
        service_code:
          allOf:
            - $ref: '#/components/schemas/service_code'
          readOnly: true
          description: >
            The carrier service used to ship the package, such as
            `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc.
        test_label:
          writeOnly: true
          type: boolean
          default: false
          deprecated: true
          description: >-
            Indicate if this label is being used only for testing purposes. If
            true, then no charge will be added to your account.
        package_code:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/package_code'
          description: >
            The package type, such as `thick_envelope`, `small_flat_rate_box`,
            `large_package`, etc.  The code `package` indicates a custom or
            unknown package type.
        validate_address:
          writeOnly: true
          default: validate_and_clean
          allOf:
            - $ref: '#/components/schemas/validate_address'
        voided:
          type: boolean
          readOnly: true
          description: |
            Indicates whether the label has been voided
        voided_at:
          type: string
          nullable: true
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: >
            The date and time that the label was voided, or `null` if the label
            has not been voided
        label_download_type:
          writeOnly: true
          default: url
          allOf:
            - $ref: '#/components/schemas/label_download_type'
        label_format:
          default: pdf
          allOf:
            - $ref: '#/components/schemas/label_format'
          description: >
            The file format that you want the label to be in.  We recommend
            `pdf` format because it is supported by all carriers, whereas some
            carriers do not support the `png` or `zpl` formats.
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
        label_layout:
          default: 4x6
          allOf:
            - $ref: '#/components/schemas/label_layout'
          description: >
            The layout (size) that you want the label to be in.  The
            `label_format` determines which sizes are allowed.  `4x6` is
            supported for all label formats, whereas `letter` (8.5" x 11") is
            only supported for `pdf` format.
        trackable:
          type: boolean
          readOnly: true
          description: >
            Indicates whether the shipment is trackable, in which case the
            `tracking_status` field will reflect the current status and each
            package will have a `tracking_number`.
        label_image_id:
          type: string
          nullable: true
          allOf:
            - $ref: '#/components/schemas/image_id'
          description: >-
            The label image resource that was used to create a custom label
            image.
        carrier_code:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/carrier_code'
          description: >
            The shipping carrier who will ship the package, such as `fedex`,
            `dhl_express`, `stamps_com`, etc.
        tracking_status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/tracking_status'
          description: >-
            The current status of the package, such as `in_transit` or
            `delivered`
        confirmation:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/delivery_confirmation'
          description: >-
            The type of delivery confirmation for this shipment. Defaults to
            'none' if not specified.
        label_download:
          allOf:
            - $ref: '#/components/schemas/label_download'
          readOnly: true
        form_download:
          type: object
          readOnly: true
          nullable: true
          allOf:
            - $ref: '#/components/schemas/link'
          description: >
            The link to download the customs form (a.k.a. commercial invoice)
            for this shipment, if any.  Forms are in PDF format. This field is
            null if the shipment does not require a customs form, or if the
            carrier does not support it.
        qr_code_download:
          type: object
          readOnly: true
          nullable: true
          allOf:
            - $ref: '#/components/schemas/optional_link'
          description: The QR code download for the package
        paperless_download:
          type: object
          readOnly: true
          nullable: true
          allOf:
            - $ref: '#/components/schemas/paperless_download'
          description: >
            The paperless details which may contain elements like `href`,
            `instructions` and `handoff_code`.
        insurance_claim:
          type: object
          readOnly: true
          nullable: true
          allOf:
            - $ref: '#/components/schemas/link'
          description: >
            The link to submit an insurance claim for the shipment.  This field
            is null if the shipment is not insured or if the insurance provider
            does not support online claim submission.
        packages:
          type: array
          readOnly: true
          description: >
            The label's package(s).


            > **Note:** Some carriers only allow one package per label.  If you
            attempt to create a multi-package label for a carrier that doesn't
            allow it, an error will be returned.
          items:
            allOf:
              - $ref: '#/components/schemas/label_package'
              - $ref: '#/components/schemas/alternative_identifiers'
        alternative_identifiers:
          type: array
          readOnly: true
          nullable: true
          description: >
            Additional information some carriers may provide by which to
            identify a given label in their system.
          items:
            $ref: '#/components/schemas/alternative_identifier'
        tracking_url:
          readOnly: true
          nullable: true
          type: string
          example: https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234
          description: >
            The URL to track the package. This URL is provided by the carrier
            and is unique to the tracking number.
        pickup_windows:
          readOnly: true
          nullable: true
          type: array
          description: >
            An array of pickup windows provided by the carrier during label
            creation. Contains time ranges when the carrier will pick up the
            package. This is particularly useful when the carrier does not
            support the Schedule Pickup method but still provides pickup date
            information during label purchase.
          items:
            type: object
            properties:
              start_at:
                allOf:
                  - $ref: '#/components/schemas/date_time'
                description: The start of the pickup window.
              end_at:
                allOf:
                  - $ref: '#/components/schemas/date_time'
                description: The end of the pickup window.
              use_time_zone_iana:
                type: string
                nullable: true
                description: >
                  The IANA time zone identifier for the pickup window (e.g.,
                  "Australia/Sydney"). When provided, start_at and end_at should
                  be interpreted in this time zone.
                example: Australia/Sydney
        ship_to:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/shipping_address_to'
          description: The recipient's mailing address
        void_type:
          allOf:
            - $ref: '#/components/schemas/void_type'
            - type: string
              nullable: true
              readOnly: true
          description: >
            Indicates how the label was voided. This field is `null` if the
            label has not been voided.
          example: manual
        refund_details:
          allOf:
            - $ref: '#/components/schemas/refund_details'
            - type: object
              nullable: true
              readOnly: true
          description: >
            Information about the Refund Assist request for this label. This
            field is `null` if the label is not eligible for Refund Assist.
    shipment:
      title: shipment
      description: >
        The information necessary to ship a package, such as the origin, the
        destination, the carrier service, and the package dimensions and weight.


        > **Note:** Either `ship_from` or `warehouse_id` must be set.
      required:
        - shipment_id
        - carrier_id
        - service_code
        - ship_date
        - created_at
        - modified_at
        - shipment_status
        - ship_to
        - ship_from
        - warehouse_id
        - return_to
        - insurance_provider
        - tags
        - packages
        - total_weight
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/partial_shipment'
    partial_shipment:
      title: partial_shipment
      type: object
      description: >
        The information necessary to ship a package, such as the origin, the
        destination, the carrier service, and the package dimensions and weight.
      additionalProperties: false
      properties:
        shipment_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the shipment
        carrier_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The carrier account that is billed for the shipping charges
        service_code:
          allOf:
            - $ref: '#/components/schemas/service_code'
          description: >
            The carrier service used to ship the package, such as
            `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc.
        shipping_rule_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            ID of the shipping rule, which you want to use to automate
            carrier/carrier service selection for the shipment. Service Group
            Rules can use dynamic ordering (_Cheapest_ or _Fastest_) to
            automatically select the best service based on live rate or transit
            data (US sellers with USA carriers only).
        external_order_id:
          type: string
          nullable: true
          description: ID that the Order Source assigned
        items:
          type: array
          default: []
          items:
            allOf:
              - $ref: '#/components/schemas/shipment_item'
          description: >
            Describe the packages included in this shipment as related to
            potential metadata that was imported from

            external order sources
        tax_identifiers:
          type: array
          nullable: true
          items:
            allOf:
              - $ref: '#/components/schemas/tax_identifier'
        external_shipment_id:
          type: string
          maxLength: 50
          nullable: true
          description: >
            A unique user-defined key to identify a shipment.  This can be used
            to retrieve the shipment.


            > **Warning:** The `external_shipment_id` is limited to 50
            characters. Any additional characters will be truncated.
        shipment_number:
          type: string
          maxLength: 50
          nullable: true
          description: >
            A non-unique user-defined number used to identify a shipment.  If
            undefined, this will match the external_shipment_id of the shipment.


            > **Warning:** The `shipment_number` is limited to 50 characters.
            Any additional characters will be truncated.
        ship_date:
          allOf:
            - $ref: '#/components/schemas/date'
          description: >
            The date that the shipment was (or will be) shipped.  ShipEngine
            will take the day of week into consideration. For example, if the
            carrier does not operate on Sundays, then a package that would have
            shipped on Sunday will ship on Monday instead.
        created_at:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time that the shipment was created in ShipEngine.
        modified_at:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time that the shipment was created or last modified.
        shipment_status:
          readOnly: true
          default: pending
          allOf:
            - $ref: '#/components/schemas/shipment_status'
          description: The current status of the shipment
        ship_to:
          allOf:
            - $ref: '#/components/schemas/shipping_address_to'
          description: The recipient's mailing address
        ship_from:
          allOf:
            - $ref: '#/components/schemas/shipping_address'
          description: >
            The shipment's origin address. If you frequently ship from the same
            location, consider creating a warehouse. Then you can simply specify
            the `warehouse_id` rather than the complete address each time.
        warehouse_id:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The warehouse that the shipment is being shipped from. Either
            `warehouse_id` or `ship_from` must be specified.
        return_to:
          allOf:
            - $ref: '#/components/schemas/shipping_address'
          description: >
            The return address for this shipment.  Defaults to the `ship_from`
            address.
        is_return:
          type: boolean
          nullable: true
          default: false
          description: >
            An optional indicator if the shipment is intended to be a return.
            Defaults to false if not provided.
        confirmation:
          default: none
          allOf:
            - $ref: '#/components/schemas/delivery_confirmation'
          description: >-
            The type of delivery confirmation for this shipment. Defaults to
            'none' if not specified.
        customs:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/international_shipment_options'
          description: >
            Customs information for international shipments.


            > **Note:** International shipments (where `ship_from.country_code`
            differs from `ship_to.country_code`) must include either `customs`
            or `advanced_options`.

            >

            > To prepay duties and taxes (DDP / PDT), set
            `customs.terms_of_trade_code` to `ddp`.

            >

            > Please note that the guaranteed prepaid duties and taxes option is
            available only for eligible ShipStation carriers.
        advanced_options:
          allOf:
            - $ref: '#/components/schemas/advanced_shipment_options'
          description: >
            Advanced shipment options.


            > **Note:** International shipments must include either `customs` or
            `advanced_options`.
        insurance_provider:
          default: none
          allOf:
            - $ref: '#/components/schemas/insurance_provider'
          description: >
            The insurance provider to use for any insured packages in the
            shipment.
        tags:
          type: array
          readOnly: true
          default: []
          minItems: 0
          items:
            allOf:
              - $ref: '#/components/schemas/tag'
          description: >
            Arbitrary tags associated with this shipment.  Tags can be used to
            categorize shipments, and shipments can be queried by their tags.
        order_source_code:
          allOf:
            - $ref: '#/components/schemas/order_source_name'
        packages:
          type: array
          minItems: 1
          items:
            allOf:
              - $ref: '#/components/schemas/package'
          description: >
            The packages in the shipment.


            > **Note:** Some carriers only allow one package per shipment.  If
            you attempt to create a multi-package shipment for a carrier that
            doesn't allow it, an error will be returned.
        total_weight:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/weight'
          description: The combined weight of all packages in the shipment
        comparison_rate_type:
          nullable: true
          type: string
          description: >-
            Calculate a rate for this shipment with the requested carrier using
            a ratecard that differs from the default.  Only supported for UPS
            and USPS.
          example: retail
        zone:
          type: integer
          format: int32
          nullable: true
          readOnly: true
          minimum: 0
          example: 6
          description: >
            Certain carriers base [their
            rates](https://blog.stamps.com/2017/09/08/usps-postal-zones/) off of

            custom zones that vary depending upon the ship_to and ship_from
            location
    shipment_status:
      title: shipment_status
      type: string
      enum:
        - pending
        - processing
        - label_purchased
        - cancelled
      description: The possible shipment status values
    tag:
      title: tag
      type: object
      description: >
        Tags are arbitrary strings that you can use to categorize shipments. For
        example, you may want to use tags to distinguish between domestic and
        international shipments, or between insured and uninsured shipments.  Or
        maybe you want to create a tag for each of your customers so you can
        easily retrieve every shipment for a customer.
      required:
        - name
      additionalProperties: false
      properties:
        tag_id:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          example: 8712
          description: An integer uniquely identifying a tag.
        name:
          type: string
          minLength: 1
          example: Fragile
          description: The tag name.
        color:
          type: string
          minLength: 1
          example: '#FF0000'
          description: A hex-coded string identifying the color of the tag.
    rate_detail:
      title: rate_detail
      type: object
      description: |
        Represents detailed information about a shipping cost
      additionalProperties: false
      properties:
        rate_detail_type:
          allOf:
            - $ref: '#/components/schemas/rate_detail_type'
          description: >
            The category of charge. Common values include `shipping` and
            `additional_fees`. DDP shipments (`customs.terms_of_trade_code:
            "ddp"`) also return `prepaid_duties`, `prepaid_taxes` and
            `prepaid_import_fees` on Wallet carriers, or `estimated_duties`,
            `estimated_taxes` and `estimated_import_fees` on BYOA (Bring Your
            Own Account) carriers.
        carrier_description:
          type: string
          example: Shipping
          description: The carrier-provided description of the charge.
        carrier_billing_code:
          type: string
          nullable: true
          example: BaseServiceCharge
          description: The carrier billing code, when provided by the carrier.
        carrier_memo:
          type: string
          nullable: true
          example: ''
          description: An optional carrier-supplied note for the charge.
        amount:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The amount of this individual charge.
        rate_detail_attributes:
          allOf:
            - $ref: '#/components/schemas/rate_detail_attributes'
          description: >-
            If applicable, contains additional data about a rate detail of a
            specific type, e.g. VAT
        billing_source:
          type: string
          example: carrier
          description: >
            The source that produced the charge. Common values are `carrier` for
            carrier-billed charges and `dutiestax` for duties and taxes on DDP
            shipments (prepaid on Wallet carriers, estimated on BYOA carriers).


            > **Note:** The casing of this value differs by endpoint. Label
            responses return lowercase values (e.g. `carrier`, `dutiestax`).
            Rate responses return PascalCase values (e.g. `Carrier`,
            `DutiesTax`). This reflects the actual API behavior.
    rate_detail_type:
      title: rate_detail_type
      type: string
      enum:
        - uncategorized
        - shipping
        - insurance
        - confirmation
        - discount
        - fuel_charge
        - additional_fees
        - tariff
        - tax
        - delivery
        - handling
        - special_goods
        - pickup
        - location_fee
        - oversize
        - returns
        - notifications
        - tip
        - duties_and_taxes
        - brokerage_fee
        - admin_fee
        - adjustment
        - prepaid_duties
        - prepaid_taxes
        - prepaid_import_fees
        - estimated_duties
        - estimated_taxes
        - estimated_import_fees
      description: >
        The possible rate detail type values. DDP shipments
        (`customs.terms_of_trade_code: ddp`) return `prepaid_duties`,
        `prepaid_taxes`, and `prepaid_import_fees` on Wallet carriers, or
        `estimated_duties`, `estimated_taxes`, and `estimated_import_fees` on
        BYOA (Bring Your Own Account) carriers.
    rate_detail_attributes:
      title: rate_detail_attributes
      type: object
      description: >
        Represents detailed information about a tax (e.g. VAT) contained in a
        shipping cost.
      additionalProperties: false
      properties:
        tax_type:
          allOf:
            - $ref: '#/components/schemas/tax_type'
        tax_percentage:
          type: number
          description: Tax percentage, e.g. 20 for 20%, added to the shipping cost
    tax_type:
      title: tax_type
      type: string
      enum:
        - vat
        - gst
        - hst
        - qst
        - pst
      description: >-
        Type of a tax added to shipping cost. Includes Canadian tax types GST
        (Goods and Services Tax), HST (Harmonized Sales Tax), QST (Quebec Sales
        Tax), and PST (Provincial Sales Tax).
    tracking_status:
      title: tracking_status
      type: string
      enum:
        - unknown
        - in_transit
        - error
        - delivered
      description: The different statuses that can apply to a shipment.
    label_package:
      title: label_package
      type: object
      description: |
        A package returned in the response from creating a shipping label
      required:
        - weight
      additionalProperties: false
      properties:
        package_id:
          readOnly: true
          type: integer
          format: int32
          description: The shipment package id
        package_code:
          allOf:
            - $ref: '#/components/schemas/package_code'
          description: >
            The package type, such as `thick_envelope`, `small_flat_rate_box`,
            `large_package`, etc.  The code `package` indicates a custom or
            unknown package type.
        weight:
          allOf:
            - $ref: '#/components/schemas/weight'
          description: The package weight
        dimensions:
          allOf:
            - $ref: '#/components/schemas/dimensions'
          description: The package dimensions
        insured_value:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          default:
            currency: USD
            amount: 0
          description: >
            The insured value of the package.  Requires the `insurance_provider`
            field of the shipment to be set.
        tracking_number:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/tracking_number'
          description: >
            The tracking number for the package.  The format depends on the
            carrier.
        label_download:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/label_download'
          description: The label download for the package
        form_download:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/optional_link'
          description: The form download for any customs that are needed
        qr_code_download:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/optional_link'
          description: The QR code download for the package
        paperless_download:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/paperless_download'
          description: >-
            The paperless details which may contain elements like `href`,
            `instructions` and `handoff_code`.
        label_messages:
          allOf:
            - $ref: '#/components/schemas/label_messages'
        external_package_id:
          type: string
          minLength: 1
          description: An external package id.
        content_description:
          type: string
          minLength: 1
          maxLength: 35
          description: >
            A short description of the package content. Required for shipments
            moving to, from, and through Mexico.
          example: Hand knitted wool socks
          nullable: true
        sequence:
          readOnly: true
          format: int32
          type: integer
          description: Package sequence
        has_label_documents:
          type: boolean
          description: Whether the package has label documents available for download
        has_form_documents:
          type: boolean
          description: Whether the package has form documents available for download
        has_qr_code_documents:
          type: boolean
          description: Whether the package has QR code documents available for download
        has_paperless_label_documents:
          type: boolean
          description: Whether the package has paperless documents available for download
    alternative_identifiers:
      title: alternative_identifiers
      type: object
      additionalProperties: false
      properties:
        alternative_identifiers:
          type: array
          readOnly: true
          nullable: true
          description: |
            Alternative identifiers associated with this package.
          items:
            $ref: '#/components/schemas/alternative_identifier'
    alternative_identifier:
      title: alternative_identifier
      type: object
      description: >
        Additional information some carriers may provide by which to identify a
        given label in their system.
      additionalProperties: false
      properties:
        type:
          type: string
          minLength: 1
          example: last_mile_tracking_number
          description: |
            The type of alternative_identifier that corresponds to the value.
        value:
          type: string
          minLength: 1
          example: '12345678912345678912'
          description: |
            The value of the alternative_identifier.
    void_type:
      title: void_type
      type: string
      enum:
        - refund_assist
        - manual
      description: >-
        Indicates how a label was voided. `refund_assist` means the label was
        voided through the Refund Assist program, while `manual` means it was
        voided manually by the user.
    refund_details:
      title: refund_details
      type: object
      description: >
        Information about a Refund Assist label. This object contains details
        about the refund request status and associated monetary amounts.
      additionalProperties: false
      properties:
        refund_status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/refund_status'
          description: The current status of the refund request
        request_date:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time when the refund request was submitted
        amount_paid:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
            - type: object
              readOnly: true
              nullable: true
          description: The amount that was originally paid for the label
        amount_requested:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
            - type: object
              readOnly: true
              nullable: true
          description: The amount requested to be refunded
        amount_approved:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
            - type: object
              readOnly: true
              nullable: true
          description: The amount approved for refund by the carrier
        amount_credited:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
            - type: object
              readOnly: true
              nullable: true
          description: The amount that has been credited back to the account
    refund_status:
      title: refund_status
      type: string
      enum:
        - request_scheduled
        - pending
        - approved
        - rejected
        - excluded
      description: >
        The status of a Refund Assist request for eligible labels.


        |Status              |Description

        |:-------------------|:-----------------------------------------------------

        |`request_scheduled` |The refund request has been scheduled but not yet
        submitted

        |`pending`           |The refund request has been submitted and is
        awaiting approval

        |`approved`          |The refund request has been approved by the
        carrier

        |`rejected`          |The refund request has been rejected by the
        carrier

        |`excluded`          |The refund request has been excluded by the user.
        Labels in this status were not sent to the carrier for a refund request.
    get_label_by_external_shipment_id_response_body:
      title: get_label_by_external_shipment_id_response_body
      description: A get label by external shipment id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/label'
    create_label_from_rate_request_body:
      title: create_label_from_rate_request_body
      description: A purchase label without shipment request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/purchase_label_without_shipment'
      properties:
        custom_field1:
          type: string
          description: >-
            Optional - Value will be saved in the shipment's advanced_options >
            custom_field1
        custom_field2:
          type: string
          description: >-
            Optional - Value will be saved in the shipment's advanced_options >
            custom_field2
        custom_field3:
          type: string
          description: >-
            Optional - Value will be saved in the shipment's advanced_options >
            custom_field3
        external_shipment_id:
          type: string
          maxLength: 100
          nullable: true
          description: >-
            Optional - A unique user-defined key to identify a shipment limited
            to 100 characters.
          example: my-shipment-001
    purchase_label_without_shipment:
      title: purchase_label_without_shipment
      type: object
      description: A purchase label without shipment resource
      additionalProperties: false
      properties:
        validate_address:
          allOf:
            - $ref: '#/components/schemas/validate_address'
        label_layout:
          default: 4x6
          allOf:
            - $ref: '#/components/schemas/label_layout'
        label_format:
          default: pdf
          allOf:
            - $ref: '#/components/schemas/label_format'
        label_download_type:
          default: url
          allOf:
            - $ref: '#/components/schemas/label_download_type'
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
    create_label_from_rate_response_body:
      title: create_label_from_rate_response_body
      description: A create label from rate response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/label'
    rate_attributes:
      title: rate_attributes
      type: string
      enum:
        - best_value
        - cheapest
        - fastest
      description: Optional attributes that indicate the most profitable rates
    create_label_rate_shopper_request_body:
      title: create_label_rate_shopper_request_body
      type: object
      description: >
        Request body for creating a label using the Rate Shopper. The Rate
        Shopper

        automatically selects the carrier and service based on your specified
        strategy.


        **Important Constraints:**

        - You MUST provide shipment details inline in the `shipment` object

        - You MUST NOT set `shipment_id` (inline shipment only)

        - You MUST NOT include `carrier_id`, `service_code`, or
        `shipping_rule_id`
          in the shipment (Rate Shopper selects these automatically)
        - Only carriers configured in your wallet will be considered

        - This endpoint is not available in sandbox mode
      additionalProperties: false
      required:
        - shipment
      properties:
        shipment:
          description: >
            The shipment details for which to create a label. Must be provided
            inline.

            The carrier_id, service_code, and shipping_rule_id are not included
            as these

            will be automatically determined by the Rate Shopper based on your
            strategy.
          allOf:
            - $ref: '#/components/schemas/partial_shipment_for_rate_shopper'
        is_return_label:
          type: boolean
          description: >
            Indicates whether this is a return label.  You may also want to set
            the `rma_number` so you know what is being returned.
        rma_number:
          type: string
          nullable: true
          description: >
            An optional Return Merchandise Authorization number.  This field is
            useful for return labels.  You can set it to any string value.
        charge_event:
          allOf:
            - $ref: '#/components/schemas/label_charge_event'
          description: |
            The label charge event.
        outbound_label_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          writeOnly: true
          description: >
            The `label_id` of the original (outgoing) label that the return
            label is for. This associates the two labels together, which is

            required by some carriers.
        test_label:
          writeOnly: true
          type: boolean
          default: false
          deprecated: true
          description: >-
            Indicate if this label is being used only for testing purposes. If
            true, then no charge will be added to your account.
        validate_address:
          writeOnly: true
          default: no_validation
          allOf:
            - $ref: '#/components/schemas/validate_address'
        label_download_type:
          writeOnly: true
          default: url
          allOf:
            - $ref: '#/components/schemas/label_download_type'
        label_format:
          default: pdf
          allOf:
            - $ref: '#/components/schemas/label_format'
          description: >
            The file format that you want the label to be in.  We recommend
            `pdf` format because it is supported by all carriers, whereas some
            carriers do not support the `png` or `zpl` formats.
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
        label_layout:
          default: 4x6
          allOf:
            - $ref: '#/components/schemas/label_layout'
          description: >
            The layout (size) that you want the label to be in.  The
            `label_format` determines which sizes are allowed.  `4x6` is
            supported for all label formats, whereas `letter` (8.5" x 11") is
            only supported for `pdf` format.
        label_image_id:
          type: string
          nullable: true
          allOf:
            - $ref: '#/components/schemas/image_id'
          description: >-
            The label image resource that was used to create a custom label
            image.
    partial_shipment_for_rate_shopper:
      title: partial_shipment_for_rate_shopper
      type: object
      description: >
        The information necessary to ship a package for Rate Shopper, such as
        the origin, the destination, and the package dimensions and weight.


        **Note:** This schema excludes carrier_id, service_code, and
        shipping_rule_id as these are automatically selected by the Rate Shopper
        based on your chosen strategy.
      additionalProperties: false
      properties:
        shipment_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the shipment
        external_order_id:
          type: string
          nullable: true
          description: ID that the Order Source assigned
        items:
          type: array
          default: []
          items:
            allOf:
              - $ref: '#/components/schemas/shipment_item'
          description: >
            Describe the packages included in this shipment as related to
            potential metadata that was imported from

            external order sources
        tax_identifiers:
          type: array
          nullable: true
          items:
            allOf:
              - $ref: '#/components/schemas/tax_identifier'
        external_shipment_id:
          type: string
          maxLength: 50
          nullable: true
          description: >
            A unique user-defined key to identify a shipment.  This can be used
            to retrieve the shipment.


            > **Warning:** The `external_shipment_id` is limited to 50
            characters. Any additional characters will be truncated.
        shipment_number:
          type: string
          maxLength: 50
          nullable: true
          description: >
            A non-unique user-defined number used to identify a shipment.  If
            undefined, this will match the external_shipment_id of the shipment.


            > **Warning:** The `shipment_number` is limited to 50 characters.
            Any additional characters will be truncated.
        ship_date:
          allOf:
            - $ref: '#/components/schemas/date'
          description: >
            The date that the shipment was (or will be) shipped.  ShipEngine
            will take the day of week into consideration. For example, if the
            carrier does not operate on Sundays, then a package that would have
            shipped on Sunday will ship on Monday instead.
        created_at:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time that the shipment was created in ShipEngine.
        modified_at:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time that the shipment was created or last modified.
        shipment_status:
          readOnly: true
          default: pending
          allOf:
            - $ref: '#/components/schemas/shipment_status'
          description: The current status of the shipment
        ship_to:
          allOf:
            - $ref: '#/components/schemas/shipping_address_to'
          description: The recipient's mailing address
        ship_from:
          allOf:
            - $ref: '#/components/schemas/shipping_address'
          description: >
            The shipment's origin address. If you frequently ship from the same
            location, consider creating a warehouse. Then you can simply specify
            the `warehouse_id` rather than the complete address each time.
        warehouse_id:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The warehouse that the shipment is being shipped from. Either
            `warehouse_id` or `ship_from` must be specified.
        return_to:
          allOf:
            - $ref: '#/components/schemas/shipping_address'
          description: >
            The return address for this shipment.  Defaults to the `ship_from`
            address.
        is_return:
          type: boolean
          nullable: true
          default: false
          description: >
            An optional indicator if the shipment is intended to be a return.
            Defaults to false if not provided.
        confirmation:
          default: none
          allOf:
            - $ref: '#/components/schemas/delivery_confirmation'
          description: >-
            The type of delivery confirmation for this shipment. Defaults to
            'none' if not specified.
        customs:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/international_shipment_options'
          description: >
            Customs information for international shipments.


            > **Note:** International shipments (where `ship_from.country_code`
            differs from `ship_to.country_code`) must include either `customs`
            or `advanced_options`.

            >

            > To prepay duties and taxes (DDP / PDT), set
            `customs.terms_of_trade_code` to `ddp`.

            >

            > Please note that the guaranteed prepaid duties and taxes option is
            available only for eligible ShipStation carriers.
        advanced_options:
          allOf:
            - $ref: '#/components/schemas/advanced_shipment_options'
          description: >
            Advanced shipment options.


            > **Note:** International shipments must include either `customs` or
            `advanced_options`.
        insurance_provider:
          default: none
          allOf:
            - $ref: '#/components/schemas/insurance_provider'
          description: >
            The insurance provider to use for any insured packages in the
            shipment.
        tags:
          type: array
          readOnly: true
          default: []
          minItems: 0
          items:
            allOf:
              - $ref: '#/components/schemas/tag'
          description: >
            Arbitrary tags associated with this shipment.  Tags can be used to
            categorize shipments, and shipments can be queried by their tags.
        order_source_code:
          allOf:
            - $ref: '#/components/schemas/order_source_name'
        packages:
          type: array
          minItems: 1
          items:
            allOf:
              - $ref: '#/components/schemas/package'
          description: >
            The packages in the shipment.


            > **Note:** Some carriers only allow one package per shipment.  If
            you attempt to create a multi-package shipment for a carrier that
            doesn't allow it, an error will be returned.
        total_weight:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/weight'
          description: The combined weight of all packages in the shipment
        comparison_rate_type:
          nullable: true
          type: string
          description: >-
            Calculate a rate for this shipment with the requested carrier using
            a ratecard that differs from the default.  Only supported for UPS
            and USPS.
          example: retail
        zone:
          type: integer
          format: int32
          nullable: true
          readOnly: true
          minimum: 0
          example: 6
          description: >
            Certain carriers base [their
            rates](https://blog.stamps.com/2017/09/08/usps-postal-zones/) off of

            custom zones that vary depending upon the ship_to and ship_from
            location
    create_label_rate_shopper_response_body:
      title: create_label_rate_shopper_response_body
      description: >
        The response from creating a label using the Rate Shopper. Includes all
        standard label information plus the rate_shopper_id indicating which
        strategy or custom rate shopper was used.
      allOf:
        - $ref: '#/components/schemas/label'
      properties:
        rate_shopper_id:
          type: string
          description: >
            The rate selection strategy or custom rate shopper ID that was used
            to create this label. This will match the rate_shopper_id provided
            in the request path.
          readOnly: true
          example: cheapest
    rate_shopper_list_response_body:
      title: rate_shopper_list_response_body
      type: object
      description: >-
        A list of rate shoppers (both default and custom) for the authenticated
        seller.
      additionalProperties: false
      required:
        - rate_shoppers
      properties:
        rate_shoppers:
          type: array
          description: >-
            The list of rate shoppers. Default rate shoppers appear first,
            followed by custom ones.
          items:
            $ref: '#/components/schemas/rate_shopper_response'
    rate_shopper_response:
      title: rate_shopper_response
      type: object
      description: |
        A rate shopper configuration. Can be a default rate shopper (cheapest,
        fastest, best_value) or a seller-created custom rate shopper.
      additionalProperties: false
      required:
        - rate_shopper_id
        - name
        - services
        - is_active
        - created_at
        - updated_at
      properties:
        rate_shopper_id:
          type: string
          description: |
            Identifier for the rate shopper. For default rate shoppers this is
            a strategy name (`cheapest`, `fastest`, `best_value`). For custom
            rate shoppers this is a UUID.
          example: cheapest
        name:
          type: string
          description: Display name of the rate shopper.
          example: Cheapest
        services:
          type: array
          description: The carrier services included in this rate shopper.
          items:
            $ref: '#/components/schemas/rate_shopper_service'
        transit_time:
          $ref: '#/components/schemas/rate_shopper_transit_time'
        service_preference:
          $ref: '#/components/schemas/rate_shopper_service_preference'
        is_active:
          type: boolean
          description: Whether the rate shopper is currently active.
          example: true
        created_at:
          type: string
          format: date-time
          description: Timestamp when the rate shopper was created.
          example: '2025-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the rate shopper was last updated.
          example: '2025-03-20T14:45:00Z'
    rate_shopper_service:
      title: rate_shopper_service
      type: object
      description: A carrier service entry in a rate shopper.
      additionalProperties: false
      required:
        - service_code
        - carrier_id
      properties:
        service_code:
          type: string
          description: The carrier service code.
          example: usps_priority_mail
        carrier_id:
          type: string
          description: The carrier account ID (prefixed with `se-`).
          example: se-28529731
    rate_shopper_transit_time:
      title: rate_shopper_transit_time
      type: object
      description: Transit time constraints for rate selection.
      additionalProperties: false
      properties:
        max_days:
          type: integer
          nullable: true
          description: Maximum transit days for domestic shipments.
          example: 5
        max_days_international:
          type: integer
          nullable: true
          description: Maximum transit days for international shipments.
          example: 14
        use_deliver_by_date:
          type: boolean
          description: Whether to use the order's deliver-by date for filtering.
          example: false
    rate_shopper_service_preference:
      title: rate_shopper_service_preference
      type: object
      description: Preferred service and price tolerance settings.
      additionalProperties: false
      properties:
        service:
          $ref: '#/components/schemas/rate_shopper_service'
        price_tolerance:
          $ref: '#/components/schemas/rate_shopper_price_tolerance'
    rate_shopper_price_tolerance:
      title: rate_shopper_price_tolerance
      type: object
      description: Price tolerance thresholds for the preferred service.
      additionalProperties: false
      required:
        - amount
        - percentage
      properties:
        amount:
          type: number
          format: decimal
          description: Maximum absolute price difference allowed.
          example: 2.5
        percentage:
          type: number
          format: decimal
          description: Maximum percentage price difference allowed.
          example: 10
    create_label_from_shipping_rule_request_body:
      title: create_label_from_shipping_rule_request_body
      type: object
      description: >
        Request body for creating a label using a Shipping Rule. The Shipping
        Rule automatically selects the carrier and service based on its
        configuration.


        **Important Constraints:**

        - You MUST NOT include `carrier_id`, `service_code`, or
        `shipping_rule_id`
          in the shipment (the Shipping Rule selects these automatically)
      additionalProperties: false
      required:
        - shipment
      properties:
        shipment:
          description: >
            The shipment details for which to create a label. The carrier_id,
            service_code, and shipping_rule_id are not allowed as these will be
            automatically determined by the Shipping Rule.
          allOf:
            - $ref: '#/components/schemas/partial_shipment_for_shipping_rule'
        is_return_label:
          type: boolean
          example: false
          description: >
            Indicates whether this is a return label.  You may also want to set
            the `rma_number` so you know what is being returned.
        rma_number:
          type: string
          nullable: true
          example: RMA-12345
          description: >
            An optional Return Merchandise Authorization number.  This field is
            useful for return labels.  You can set it to any string value.
        charge_event:
          allOf:
            - $ref: '#/components/schemas/label_charge_event'
          description: |
            The label charge event.
        outbound_label_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          writeOnly: true
          description: >
            The `label_id` of the original (outgoing) label that the return
            label is for. This associates the two labels together, which is

            required by some carriers.
        test_label:
          writeOnly: true
          type: boolean
          default: false
          deprecated: true
          example: false
          description: >-
            Indicate if this label is being used only for testing purposes. If
            true, then no charge will be added to your account.
        validate_address:
          writeOnly: true
          default: no_validation
          allOf:
            - $ref: '#/components/schemas/validate_address'
        label_download_type:
          writeOnly: true
          default: url
          allOf:
            - $ref: '#/components/schemas/label_download_type'
        label_format:
          default: pdf
          allOf:
            - $ref: '#/components/schemas/label_format'
          description: >
            The file format that you want the label to be in.  We recommend
            `pdf` format because it is supported by all carriers, whereas some
            carriers do not support the `png` or `zpl` formats.
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
        label_layout:
          default: 4x6
          allOf:
            - $ref: '#/components/schemas/label_layout'
          description: >
            The layout (size) that you want the label to be in.  The
            `label_format` determines which sizes are allowed.  `4x6` is
            supported for all label formats, whereas `letter` (8.5" x 11") is
            only supported for `pdf` format.
        label_image_id:
          type: string
          nullable: true
          allOf:
            - $ref: '#/components/schemas/image_id'
          description: >-
            The label image resource that was used to create a custom label
            image.
    partial_shipment_for_shipping_rule:
      title: partial_shipment_for_shipping_rule
      type: object
      description: >
        The information necessary to ship a package using a Shipping Rule, such
        as the origin, the destination, and the package dimensions and weight.


        **Note:** This schema excludes carrier_id, service_code, and
        shipping_rule_id as these are automatically selected by the Shipping
        Rule based on its configuration.
      additionalProperties: false
      properties:
        external_order_id:
          type: string
          nullable: true
          example: ext-order-123
          description: ID that the Order Source assigned
        items:
          type: array
          default: []
          items:
            allOf:
              - $ref: '#/components/schemas/shipment_item'
          description: >
            Describe the packages included in this shipment as related to
            potential metadata that was imported from

            external order sources
        tax_identifiers:
          type: array
          nullable: true
          items:
            allOf:
              - $ref: '#/components/schemas/tax_identifier'
        external_shipment_id:
          type: string
          maxLength: 50
          nullable: true
          example: ext-ship-123
          description: >
            A unique user-defined key to identify a shipment.  This can be used
            to retrieve the shipment.


            > **Warning:** The `external_shipment_id` is limited to 50
            characters. Any additional characters will be truncated.
        shipment_number:
          type: string
          maxLength: 50
          nullable: true
          example: SHIP-001
          description: >
            A non-unique user-defined number used to identify a shipment.  If
            undefined, this will match the external_shipment_id of the shipment.


            > **Warning:** The `shipment_number` is limited to 50 characters.
            Any additional characters will be truncated.
        ship_date:
          allOf:
            - $ref: '#/components/schemas/date'
          description: >
            The date that the shipment was (or will be) shipped.  ShipEngine
            will take the day of week into consideration. For example, if the
            carrier does not operate on Sundays, then a package that would have
            shipped on Sunday will ship on Monday instead.
        ship_to:
          allOf:
            - $ref: '#/components/schemas/shipping_address_to'
          description: The recipient's mailing address
        ship_from:
          allOf:
            - $ref: '#/components/schemas/shipping_address_from'
          description: >
            The shipment's origin address. If you frequently ship from the same
            location, consider creating a warehouse. Then you can simply specify
            the `warehouse_id` rather than the complete address each time.
        warehouse_id:
          type: string
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The warehouse that the shipment is being shipped from. Either
            `warehouse_id` or `ship_from` must be specified.
        return_to:
          allOf:
            - $ref: '#/components/schemas/shipping_address'
          description: >
            The return address for this shipment.  Defaults to the `ship_from`
            address.
        is_return:
          type: boolean
          nullable: true
          default: false
          example: false
          description: >
            An optional indicator if the shipment is intended to be a return.
            Defaults to false if not provided.
        confirmation:
          default: none
          allOf:
            - $ref: '#/components/schemas/delivery_confirmation'
          description: >-
            The type of delivery confirmation for this shipment. Defaults to
            'none' if not specified.
        customs:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/international_shipment_options'
          description: >
            Customs information for international shipments.


            > **Note:** International shipments (where `ship_from.country_code`
            differs from `ship_to.country_code`) must include either `customs`
            or `advanced_options`.

            >

            > To prepay duties and taxes (DDP / PDT), set
            `customs.terms_of_trade_code` to `ddp`.

            >

            > Please note that the guaranteed prepaid duties and taxes option is
            available only for eligible ShipStation carriers.
        advanced_options:
          allOf:
            - $ref: '#/components/schemas/advanced_shipment_options'
          description: >
            Advanced shipment options.


            > **Note:** International shipments must include either `customs` or
            `advanced_options`.
        insurance_provider:
          default: none
          allOf:
            - $ref: '#/components/schemas/insurance_provider'
          description: >
            The insurance provider to use for any insured packages in the
            shipment.
        order_source_code:
          allOf:
            - $ref: '#/components/schemas/order_source_name'
        packages:
          type: array
          minItems: 1
          items:
            allOf:
              - $ref: '#/components/schemas/package'
          description: >
            The packages in the shipment.


            > **Note:** Some carriers only allow one package per shipment.  If
            you attempt to create a multi-package shipment for a carrier that
            doesn't allow it, an error will be returned.
        comparison_rate_type:
          nullable: true
          type: string
          description: >-
            Calculate a rate for this shipment with the requested carrier using
            a ratecard that differs from the default.  Only supported for UPS
            and USPS.
          example: retail
    create_label_from_shipment_request_body:
      title: create_label_from_shipment_request_body
      type: object
      description: A purchase label without shipment request body
      additionalProperties: false
      properties:
        validate_address:
          allOf:
            - $ref: '#/components/schemas/validate_address'
        label_layout:
          default: 4x6
          allOf:
            - $ref: '#/components/schemas/label_layout'
        label_format:
          default: pdf
          allOf:
            - $ref: '#/components/schemas/label_format'
        label_download_type:
          default: url
          allOf:
            - $ref: '#/components/schemas/label_download_type'
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
    create_label_from_shipment_response_body:
      title: create_label_from_shipment_response_body
      description: A create label from shipment response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/label'
    get_label_by_id_response_body:
      title: get_label_by_id_response_body
      description: A get label by id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/label'
    create_return_label_request_body:
      title: create_return_label_request_body
      type: object
      description: A create return label request body
      additionalProperties: false
      properties:
        charge_event:
          allOf:
            - $ref: '#/components/schemas/label_charge_event'
          description: |
            The label charge event.
        label_layout:
          default: 4x6
          allOf:
            - $ref: '#/components/schemas/label_layout'
          description: >
            The layout (size) that you want the label to be in.  The
            `label_format` determines which sizes are allowed.  `4x6` is
            supported for all label formats, whereas `letter` (8.5" x 11") is
            only supported for `pdf` format.
        label_format:
          default: pdf
          allOf:
            - $ref: '#/components/schemas/label_format'
          description: >
            The file format that you want the label to be in.  We recommend
            `pdf` format because it is supported by all carriers, whereas some
            carriers do not support the `png` or `zpl` formats.
        label_download_type:
          writeOnly: true
          default: url
          allOf:
            - $ref: '#/components/schemas/label_download_type'
        display_scheme:
          default: label
          allOf:
            - $ref: '#/components/schemas/display_scheme'
          description: The display format that the label should be shown in.
        label_image_id:
          type: string
          nullable: true
          allOf:
            - $ref: '#/components/schemas/image_id'
          description: >-
            The label image resource that was used to create a custom label
            image.
        rma_number:
          type: string
          nullable: true
          description: >
            An optional Return Merchandise Authorization number. If provided,
            this value will be used as the return label's RMA number. If
            omitted, the system will auto-generate an RMA number (current
            default behavior). You can set it to any string value.
    create_return_label_response_body:
      title: create_return_label_response_body
      description: A create return label response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/label'
    get_tracking_log_from_label_response_body:
      title: get_tracking_log_from_label_response_body
      description: A get tracking log from label response body
      required:
        - tracking_number
        - status_code
        - carrier_status_code
        - events
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/tracking_information'
    tracking_information:
      title: tracking_information
      type: object
      description: A tracking information resource
      additionalProperties: false
      properties:
        tracking_number:
          allOf:
            - $ref: '#/components/schemas/tracking_number'
        tracking_url:
          type: string
          readOnly: true
          example: https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234
          description: Carrier Tracking Url, if available
        status_code:
          allOf:
            - $ref: '#/components/schemas/status_code'
          example: DE
        status_detail_code:
          allOf:
            - $ref: '#/components/schemas/status_detail_code'
          example: DELIVERED
        carrier_code:
          allOf:
            - $ref: '#/components/schemas/carrier_code'
        carrier_id:
          readOnly: true
          type: integer
          format: int32
          description: >
            The unique ID of the carrier account that was used to create this
            label
        status_description:
          type: string
          readOnly: true
          example: Delivered
          minLength: 0
          description: Status description
        status_detail_description:
          type: string
          readOnly: true
          example: Your parcel has been successfully delivered.
          minLength: 0
          description: Status detail description
        carrier_status_code:
          type: string
          readOnly: true
          minLength: 1
          example: '1'
          description: Carrier status code
        carrier_detail_code:
          type: string
          readOnly: true
          minLength: 1
          example: OT
          description: Carrier detail code
        carrier_status_description:
          type: string
          minLength: 0
          readOnly: true
          example: Your item was delivered in or at the mailbox at 9:10 am on March
          description: carrier status description
        ship_date:
          allOf:
            - $ref: '#/components/schemas/date_time'
        estimated_delivery_date:
          allOf:
            - $ref: '#/components/schemas/date_time'
        actual_delivery_date:
          allOf:
            - $ref: '#/components/schemas/date_time'
        exception_description:
          type: string
          readOnly: true
          minLength: 0
          description: Exception description
        events:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/track_event'
          description: >-
            The events that have occured during the lifetime of this tracking
            number.
    status_code:
      readOnly: true
      title: status_code
      enum:
        - UN
        - AC
        - IT
        - DE
        - EX
        - AT
        - NY
        - SP
      type: string
      description: |
        The tracking status codes

        |Value       |Description
        |:---------  |:-----------------------------------------------------
        |`UN` | Unknown
        |`AC` | Accepted
        |`IT` | In Transit
        |`DE` | Delivered
        |`EX` | Exception
        |`AT` | Delivery Attempt
        |`NY` | Not Yet In System
        |`SP` | Delivered To Collection Location
    status_detail_code:
      readOnly: true
      title: status_detail_code
      enum:
        - CARRIER_STATUS_NOT_MAPPED
        - SHIPMENT_CREATED
        - AWAITING_PICKUP_DROP_OFF
        - DROPPED_OFF
        - ELEC_ADVICE_RECD_BY_CARRIER
        - PICKED_UP
        - CUSTOMS_CLEARED
        - CUSTOMS_PROCESSING
        - DELIVERY_ARRANGED_WITH_RECIPIENT
        - HUB_SCAN_OUT
        - HUB_SCAN_IN
        - IN_TRANSIT
        - INFORMATION
        - PARCEL_OVER_LABELLED
        - PARCEL_UPDATE_NOTIFICATION
        - RECEIVED_BY_CARRIER
        - RECEIVED_LOCAL_DELIVERY_DEPOT
        - SUB_CONTRACTOR_EVENT
        - SUB_CONTRACTOR_RECEIVED
        - PARCEL_REDIRECTED
        - DELIVERY_SCHEDULED
        - HUB_PROCESSING
        - DELIVERY_RESCHEDULED
        - ATTEMPTED_DELIVERY
        - ATTEMPTED_DELIVERY_FINAL
        - COD_AMOUNT_PAID
        - CUSTOMER_CARDED
        - OUT_FOR_DELIVERY
        - AWAITING_COLLECTION_FROM_PICKUP_POINT
        - COLLECT_AT_LOCAL_PO
        - CUSTOMER_TO_COLLECT_FROM_CARRIER
        - DELIVERED_TO_RECEPTION
        - DELIVERED
        - DELIVERED_DAMAGED
        - DELIVERED_IN_PART
        - DELIVERED_SPECIFIED_SAFE_PLACE
        - DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION
        - DELIVERED_TO_NEIGHBOUR
        - DELIVERED_TO_PO_BOX
        - PARCEL_COLLECTED_FROM_PICKUP_POINT
        - POST_TRANSIT_STATUS
        - PROOF_OF_DELIVERY
        - PICKUP_FAILED
        - NOT_YET_RECEIVED_BY_CARRIER
        - PARCEL_DAMAGED
        - ADDRESS_QUERY
        - CARRIER_DELAYS
        - DELAYED_NOT_CARRIER
        - HELD_BY_CARRIER
        - HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSING
        - HELD_BY_CUSTOMS
        - INCORRECT_DECLARATION
        - MISROUTED
        - PARCEL_REPACKED
        - RECD_BY_CARRIER_NO_ELEC_ADVICE
        - COD_AMOUNT_NOT_PAID
        - CUSTOMER_IDENTIFICATION_FAILED
        - NO_ACCESS_TO_RECIPIENTS_ADDRESS
        - CANCELLED
        - CUSTOMER_MOVED
        - HAZARDOUS_PROHIBITED
        - NOT_COLLECTED_FROM_PICKUP_POINT
        - NOT_DELIVERED
        - NOT_DELIVERED_ADDRESSEE_DECEASED
        - PARCEL_DISPOSED
        - PARCEL_LOST
        - PARCEL_OUTSIDE_OF_SERVICE_CAPABILITY
        - REFUSED_BY_CUSTOMER
        - RETURN_TO_SENDER
        - UNSPECIFIED_EXCEPTION
        - TRACKING_EXPIRED
        - DUTY_NOT_PAID
        - PARCEL_REDIRECTED_BY_CARRIER
        - DELIVERED_TO_PICKUP_POINT
        - UNDELIVERABLE_RETURNED_TO_SENDER
      type: string
      description: >
        The tracking status detail codes


        |Value       |Description

        |:---------  |:-----------------------------------------------------

        | `CARRIER_STATUS_NOT_MAPPED` | Status not mapped. Please check the
        carrier's website for updates.

        | `SHIPMENT_CREATED` | Your tracking number is ready. Your parcel is
        waiting to be registered in the carrier system and scheduled for pickup.

        | `AWAITING_PICKUP_DROP_OFF` | Your parcel is waiting to be handed over
        to the carrier.

        | `DROPPED_OFF` | Your parcel has been dropped off and is ready for
        carrier processing.

        | `ELEC_ADVICE_RECD_BY_CARRIER` | Your shipment is now in the carrier's
        system.

        | `PICKED_UP` | Your parcel has been picked up by the carrier.

        | `CUSTOMS_CLEARED` | Your parcel has cleared customs and is continuing
        its journey.

        | `CUSTOMS_PROCESSING` | Your parcel is currently being processed by
        customs.

        | `DELIVERY_ARRANGED_WITH_RECIPIENT` | Your parcel's delivery has been
        arranged with the carrier.

        | `HUB_SCAN_OUT` | Your parcel has left the carrier's hub.

        | `HUB_SCAN_IN` | Your parcel has arrived at the carrier's hub for
        processing.

        | `IN_TRANSIT` | Your shipment is on its way between the carrier hubs.

        | `INFORMATION` | The carrier has shared additional information about
        your parcel.

        | `PARCEL_OVER_LABELLED` | Your parcel's label has been updated by the
        carrier, which may affect tracking visibility.

        | `PARCEL_UPDATE_NOTIFICATION` | The carrier has sent you an update on
        your parcel status via SMS or email.

        | `RECEIVED_BY_CARRIER` | Your parcel has been received by the carrier
        and is beginning its journey.

        | `RECEIVED_LOCAL_DELIVERY_DEPOT` | Your parcel has arrived at the local
        delivery depot and is almost ready for delivery.

        | `SUB_CONTRACTOR_EVENT` | The carrier has shared additional information
        about your parcel's handling by a delivery partner.

        | `SUB_CONTRACTOR_RECEIVED` | Your parcel has been received by the
        carrier's local delivery partner.

        | `PARCEL_REDIRECTED` | Your parcel has been redirected to a new
        delivery address per your request.

        | `DELIVERY_SCHEDULED` | Your parcel's delivery has been scheduled and
        will soon be out for delivery.

        | `HUB_PROCESSING` | Your parcel is being processed at a carrier hub.

        | `DELIVERY_RESCHEDULED` | Your parcel's delivery has been rescheduled
        due to operational issues.

        | `ATTEMPTED_DELIVERY` | The carrier attempted to deliver your parcel
        but was unable to complete delivery.

        | `ATTEMPTED_DELIVERY_FINAL` | The carrier made a final attempt to
        deliver your parcel but was unable to complete delivery. Please check
        the carrier's instructions for next steps.

        | `COD_AMOUNT_PAID` | Cash on delivery payment received.

        | `CUSTOMER_CARDED` | Delivery attempt failed. Please follow delivery
        instructions left by the carrier.

        | `OUT_FOR_DELIVERY` | Your parcel is on its way and will be delivered
        today.

        | `AWAITING_COLLECTION_FROM_PICKUP_POINT` | Your parcel is ready for
        collection at the selected pickup point.

        | `COLLECT_AT_LOCAL_PO` | Your parcel is ready for collection at your
        local post office.

        | `CUSTOMER_TO_COLLECT_FROM_CARRIER` | Your parcel is available for
        collection from the carrier's local delivery unit.

        | `DELIVERED_TO_RECEPTION` | Your parcel has been delivered to your
        building's reception or designated mail area.

        | `DELIVERED` | Your parcel has been successfully delivered.

        | `DELIVERED_DAMAGED` | Your parcel was delivered but arrived with
        visible damage.

        | `DELIVERED_IN_PART` | Part of your shipment has been delivered. Check
        for updates on the rest.

        | `DELIVERED_SPECIFIED_SAFE_PLACE` | Your parcel has been delivered to
        your specified safe place.

        | `DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION` | Your parcel was
        delivered to an alternative location due to the delivery company being
        unable to deliver it to the specified address. Check carrier
        instructions for pickup details.

        | `DELIVERED_TO_NEIGHBOUR` | Your parcel was delivered to your neighbor.

        | `DELIVERED_TO_PO_BOX` | Your parcel has been delivered to your
        specified PO Box.

        | `PARCEL_COLLECTED_FROM_PICKUP_POINT` | Your package has been picked up
        from the pick up point.

        | `POST_TRANSIT_STATUS` | The carrier has added more information about
        your delivery.

        | `PROOF_OF_DELIVERY` | The carrier has confirmed delivery with proof,
        such as a signature or photo.

        | `PICKUP_FAILED` | Parcel pickup failed. The delivery company will try
        again soon.

        | `NOT_YET_RECEIVED_BY_CARRIER` | The carrier has not yet received your
        parcel, which may cause a delay.

        | `PARCEL_DAMAGED` | Your parcel was damaged in transit but will still
        be delivered.

        | `ADDRESS_QUERY` | There is an issue with the delivery address, which
        may delay your parcel.

        | `CARRIER_DELAYS` | Your parcel is delayed due to issues within the
        carrier network.

        | `DELAYED_NOT_CARRIER` | Your parcel is delayed due to circumstances
        beyond the carrier's control.

        | `HELD_BY_CARRIER` | Your parcel is being held due to an operational
        issue. Contact with the carrier for more information.

        | `HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSING` | Your parcel is being
        held by the carrier for customs documentation checks. This may occur
        when the carrier must confirm documentation before the parcel can
        continue its journey.

        | `HELD_BY_CUSTOMS` | Your parcel is being held at customs, which may
        delay delivery.

        | `INCORRECT_DECLARATION` | Your parcel has been incorrectly declared
        but is still moving forward for delivery.

        | `MISROUTED` | Your parcel was sent to the wrong place due to a routing
        error but is being redirected.

        | `PARCEL_REPACKED` | Your parcel was repackaged by the carrier due to
        damage and will still be delivered.

        | `RECD_BY_CARRIER_NO_ELEC_ADVICE` | Your parcel has been received by
        the carrier but may experience delays due to missing pre-advice.

        | `COD_AMOUNT_NOT_PAID` | Delivery failed due to unpaid cash on
        delivery. Please follow carrier instructions.

        | `CUSTOMER_IDENTIFICATION_FAILED` | Delivery couldn't be completed as
        identification requirements were not met.

        | `NO_ACCESS_TO_RECIPIENTS_ADDRESS` | The carrier couldn't access the
        delivery location due to restricted entry.

        | `CANCELLED` | Your parcel has been cancelled.

        | `CUSTOMER_MOVED` | Delivery failed as the recipient is no longer at
        the specified address. Your parcel is being returned.

        | `HAZARDOUS_PROHIBITED` | Your parcel contains restricted items and
        will not be delivered.

        | `NOT_COLLECTED_FROM_PICKUP_POINT` | Your parcel was not collected from
        the pickup point within the designated time and will be returned.

        | `NOT_DELIVERED` | All delivery attempts failed. Your parcel is being
        returned to the sender.

        | `NOT_DELIVERED_ADDRESSEE_DECEASED` | The parcel could not be delivered
        as the addressee is reported deceased.

        | `PARCEL_DISPOSED` | Your parcel has been disposed of due to its
        contents or condition and will not be delivered.

        | `PARCEL_LOST` | The carrier has reported that your parcel is lost and
        will not be delivered.

        | `PARCEL_OUTSIDE_OF_SERVICE_CAPABILITY` | The parcel cannot be
        delivered as it exceeds the carrier's service limits.

        | `REFUSED_BY_CUSTOMER` | You have refused the parcel, and it will be
        returned to the sender.

        | `RETURN_TO_SENDER` | Your parcel is being returned to the sender due
        to delivery issues.

        | `UNSPECIFIED_EXCEPTION` | The carrier has reported an issue with your
        parcel, but details are unavailable.

        | `TRACKING_EXPIRED` | Tracking for this parcel has expired. If you are
        still expecting this delivery, please contact the carrier for
        assistance.

        | `DUTY_NOT_PAID` | The import taxes or duties for this package havent
        been paid and it may be subject to disposal by customs authorities if
        payment is not made.

        | `PARCEL_REDIRECTED_BY_CARRIER` | The carrier has redirected your
        parcel due to an operational issue. The package is likely being rerouted
        to a nearby pickup point. You may contact the carrier for more details
        about the new delivery location.

        | `DELIVERED_TO_PICKUP_POINT` | Your package has been delivered to the
        pickup point. You will be notified when its ready for collection.

        | `UNDELIVERABLE_RETURNED_TO_SENDER` | The shipment has been returned to
        the sender. Please contact the sender for further information.
    track_event:
      title: track_event
      type: object
      description: A track event
      required:
        - occurred_at
        - city_locality
        - state_province
        - postal_code
        - carrier_detail_code
        - status_code
        - status_description
        - carrier_status_code
        - carrier_status_description
      additionalProperties: false
      properties:
        occurred_at:
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: Timestamp for carrier event
        carrier_occurred_at:
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: >-
            Carrier timestamp for the event, it is assumed to be the local time
            of where the event occurred.
        description:
          type: string
          readOnly: true
          minLength: 0
          example: Delivered, In/At Mailbox
          description: Event description
        city_locality:
          type: string
          readOnly: true
          example: AUSTIN
          minLength: 0
          description: City locality
        state_province:
          type: string
          readOnly: true
          example: TX
          minLength: 2
          description: State province
        postal_code:
          type: string
          readOnly: true
          example: '78756'
          minLength: 0
          description: Postal code
        country_code:
          allOf:
            - $ref: '#/components/schemas/country_code'
        company_name:
          type: string
          readOnly: true
          example: Stamps.com
          minLength: 0
          description: Company Name
        signer:
          type: string
          minLength: 0
          readOnly: true
          description: Signer information
        event_code:
          type: string
          minLength: 0
          description: Event Code
        carrier_detail_code:
          type: string
          readOnly: true
          minLength: 1
          example: OT
          description: Carrier detail code
        status_code:
          allOf:
            - $ref: '#/components/schemas/status_code'
          example: IT
        status_detail_code:
          allOf:
            - $ref: '#/components/schemas/status_detail_code'
          example: IN_TRANSIT
        status_description:
          type: string
          readOnly: true
          minLength: 1
          example: In Transit
          description: Event Status Description
        status_detail_description:
          type: string
          readOnly: true
          minLength: 0
          example: Your shipment is on its way between the carrier hubs.
          description: Event Status Detail Description
        carrier_status_code:
          type: string
          readOnly: true
          minLength: 1
          example: '1'
          description: Carrier status code
        carrier_status_description:
          type: string
          minLength: 0
          readOnly: true
          example: Your item was delivered in or at the mailbox at 9:10 am on March
          description: carrier status description
        latitude:
          type: number
          format: double
          minimum: -90
          maximum: 90
          description: Latitude coordinate of tracking event.
        longitude:
          type: number
          format: double
          minimum: -180
          maximum: 180
          description: Longitude coordinate of tracking event.
        proof_of_delivery_url:
          type: string
          readOnly: true
          example: >-
            https://tracking-service-prod.s3.amazonaws.com/proof-of-delivery/dummy_module/0000000001/bc6dd17969bd97f24262ca73ac6ff36062aafecba25ef16d4178264bf7c0e72c.png
          description: >-
            A URL to an image captured at the time of delivery, serving as
            evidence that the shipment was successfully delivered to the
            recipient. It can be used to capture things like recipient's
            signature, location of delivery, condition of the package upon
            delivery, etc.
    void_label_response_body:
      title: void_label_response_body
      type: object
      description: A void label response body
      required:
        - approved
        - message
      additionalProperties: false
      properties:
        approved:
          type: boolean
          readOnly: true
          example: false
          description: Indicates whether the attempt to void the label was successful
        message:
          type: string
          minLength: 0
          readOnly: true
          example: >-
            Unable to delete FedEx shipment. Unable to retrieve record from
            database.
        voided_label_ids:
          readOnly: true
          type: array
          items:
            type: integer
            format: int64
          description: >-
            The Ids of any associated labels that were also voided as part of
            this request. Includes the originally requested label.
        reason_code:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/reason_code'
          description: >-
            Indicates a normalized reason for the conditions if the void attempt
            was not approved. Will not populate if approved is true. “unknown”
            codes may be specified later.
          example: label_not_found_within_void_period
    reason_code:
      title: reason_code
      type: string
      enum:
        - unknown
        - unspecified
        - validation_failed
        - label_not_found_within_void_period
        - label_already_used
        - label_already_voided
        - contact_carrier
      description: >-
        The possible normalized reasons a label void request may not have been
        approved
    cancel_refund_label_response_body:
      title: cancel_refund_label_response_body
      type: object
      description: A cancel refund label response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/label'
    list_manifests_response_body:
      title: list_manifests_response_body
      type: object
      description: A list manifests response body
      required:
        - manifests
        - total
        - page
        - pages
        - links
      additionalProperties: false
      properties:
        manifests:
          type: array
          readOnly: true
          default: []
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/manifest'
            description: A single manifest
          description: The list of available manifests
        total:
          type: integer
          format: int64
          readOnly: true
          minimum: 0
          example: 3
          description: The total number of manifests returned
        page:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          example: 3
          description: Current page of the list manifests results
        pages:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          example: 4
          description: Total number of pages for list manifests results
        links:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/pagination_link'
          description: Helpful links to other pages of results
    manifest:
      title: manifest
      type: object
      description: >
        Used for combining packages into one scannable form that a carrier can
        use when picking up a large

        number of shipments
      additionalProperties: false
      properties:
        manifest_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the manifest
        form_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the form
        created_at:
          type: string
          format: date-time
          minLength: 1
          readOnly: true
          example: '2019-07-12T13:37:39.050Z'
          description: The date-time that the manifest was created
        ship_date:
          type: string
          format: date-time
          minLength: 1
          readOnly: true
          example: '2019-07-12T13:37:39.050Z'
          description: The date-time that the manifests shipments will be picked up
        shipments:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          example: 100
          description: The number of shipments that are included in this manifest
        label_ids:
          type: array
          readOnly: true
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
          description: An array of the label ids used in this manifest.
        warehouse_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the warehouse
        submission_id:
          readOnly: true
          type: string
          minLength: 1
          example: '9475711899564878915476'
          description: A string that uniquely identifies the submission
        carrier_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the carrier
        manifest_download:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/manifest_download'
    manifest_download:
      title: manifest_download
      type: object
      description: Object containing the href link to download the manifest file
      additionalProperties: false
      properties:
        href:
          allOf:
            - $ref: '#/components/schemas/url'
          description: The URL of the linked resource, if any
    create_manifest_request_body:
      title: create_manifest_request_body
      oneOf:
        - $ref: '#/components/schemas/create_manifest_by_object_request_body'
        - $ref: '#/components/schemas/create_manifest_label_ids_request_body'
    create_manifest_by_object_request_body:
      title: create_manifest_by_object_request_body
      type: object
      description: A create manifest request body
      required:
        - carrier_id
        - warehouse_id
        - ship_date
      additionalProperties: false
      properties:
        carrier_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the carrier
        excluded_label_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
            description: Label Id that will be excluded from the manifest
          description: The list of label ids to exclude from the manifest
        label_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
            description: Label Id that will be included for the manifest
          description: The list of label ids to include for the manifest
        warehouse_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the warehouse
        ship_date:
          type: string
          format: date-time
          minLength: 1
          example: '2018-09-23T15:00:00.000Z'
          description: The ship date that the shipment will be sent out on
    create_manifest_label_ids_request_body:
      title: create_manifest_label_ids_request_body
      type: object
      description: A create manifest request body
      required:
        - label_ids
      additionalProperties: false
      properties:
        label_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
            description: Label Id that will be included in the manifest
          description: The list of label ids to include in the manifest
    create_manifest_response_body:
      title: create_manifest_response_body
      description: A create manifest response body
      required:
        - manifest_id
        - form_id
        - created_at
        - ship_date
        - shipments
        - warehouse_id
        - submission_id
        - carrier_id
        - manifest_download
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/manifests'
        - $ref: '#/components/schemas/manifests_requests'
        - $ref: '#/components/schemas/deprecated_manifest'
        - $ref: '#/components/schemas/error_with_label_id_response_body'
    manifests:
      title: manifests
      type: object
      description: An array of manifest resources
      additionalProperties: false
      properties:
        manifests:
          description: Resulting Manifests
          type: array
          items:
            $ref: '#/components/schemas/manifest'
    manifests_requests:
      title: manifests_requests
      type: object
      description: An array of manifest requests
      additionalProperties: false
      properties:
        manifest_requests:
          description: Resulting manifest requests with statuses
          type: array
          items:
            $ref: '#/components/schemas/manifest_request'
    manifest_request:
      title: manifest_request
      type: object
      description: A reference to the manifest request
      additionalProperties: false
      properties:
        manifest_request_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies a manifest request
        status:
          allOf:
            - $ref: '#/components/schemas/manifest_request_status'
    manifest_request_status:
      title: manifest_request_status
      type: string
      enum:
        - in_progress
        - completed
      description: The possible statuses of a manifest request
    deprecated_manifest:
      title: deprecated_manifest
      type: object
      description: Deprecated manifest resource
      additionalProperties: false
      properties:
        manifest_id:
          deprecated: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the manifest
        form_id:
          deprecated: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the form
        created_at:
          deprecated: true
          type: string
          format: date-time
          minLength: 1
          example: '2019-07-12T13:37:39.050Z'
          description: The date-time that the manifest was created
        ship_date:
          deprecated: true
          type: string
          format: date-time
          minLength: 1
          example: '2019-07-12T13:37:39.050Z'
          description: The date-time that the manifests shipments will be picked up
        shipments:
          deprecated: true
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          example: 100
          description: The number of shipments that are included in this manifest
        warehouse_id:
          deprecated: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the warehouse
        submission_id:
          deprecated: true
          type: string
          minLength: 1
          example: '9475711899564878915476'
          description: A string that uniquely identifies the submission
        carrier_id:
          deprecated: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the carrier
        manifest_download:
          deprecated: true
          allOf:
            - $ref: '#/components/schemas/manifest_download'
        label_ids:
          deprecated: true
          type: array
          readOnly: true
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
          description: An array of the label ids used in this manifest.
    error_with_label_id_response_body:
      title: error_with_label_id_response_body
      type: object
      description: An error response body
      required:
        - request_id
        - errors
      additionalProperties: false
      properties:
        request_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: >
            A UUID that uniquely identifies the request id.

            This can be given to the support team to help debug non-trivial
            issues that may occur
        errors:
          type: array
          readOnly: true
          items:
            allOf:
              - $ref: '#/components/schemas/error'
          description: The errors associated with the failed API call
    get_manifest_by_id_response_body:
      title: get_manifest_by_id_response_body
      description: A get manifest by id response body
      required:
        - manifest_id
        - form_id
        - created_at
        - ship_date
        - shipments
        - warehouse_id
        - submission_id
        - carrier_id
        - manifest_download
        - label_ids
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/manifest'
    list_package_types_response_body:
      title: list_package_types_response_body
      type: object
      description: A list package types response body
      additionalProperties: false
      properties:
        packages:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/package_type_response'
            description: Custom Package Types items
          description: An array of custom package types
    create_package_type_request_body:
      title: create_package_type_request_body
      description: A create package type request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/package_type_request'
    create_package_type_response_body:
      title: create_package_type_response_body
      description: A create package type response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/package_type_response'
    get_package_type_by_id_response_body:
      title: get_package_type_by_id_response_body
      description: A get package type by id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/package_type_response'
    update_package_type_request_body:
      title: update_package_type_request_body
      description: An update package type request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/package_type_request'
    get_pickups_response_body:
      title: get_pickups_response_body
      allOf:
        - $ref: '#/components/schemas/list_pickup_response_body'
        - $ref: '#/components/schemas/error_response_body'
    list_pickup_response_body:
      title: list_pickup_response_body
      type: object
      description: A list pickup response body
      required:
        - pickups
        - total
        - page
        - pages
        - links
      additionalProperties: false
      properties:
        pickups:
          type: array
          description: An array of pickups associated with the user's account.
          items:
            allOf:
              - $ref: '#/components/schemas/pickup'
        total:
          type: integer
          format: int64
          readOnly: true
          minimum: 0
          example: 3
          description: The total number of pickups returned
        page:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          example: 3
          description: Current page of the list pickups results
        pages:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          example: 4
          description: Total number of pages for list pickups results
        links:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/pagination_link'
          description: Helpful links to other pages of results
    pickup:
      title: pickup
      type: object
      description: |
        The information necessary to schedule a package pickup
      additionalProperties: false
      properties:
        pickup_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/pickup_resource_id'
        label_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
            description: Label ID that will be included in the pickup request
          description: Label IDs that will be included in the pickup request
        created_at:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time that the pickup was created in ShipEngine.
        cancelled_at:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: The date and time that the pickup was cancelled in ShipEngine.
        carrier_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The carrier_id associated with the pickup
        confirmation_number:
          readOnly: true
          type: string
          nullable: true
          description: The carrier confirmation number for the scheduled pickup.
          example: 292513CL4A3
        warehouse_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The warehouse_id associated with the pickup
        pickup_address:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/address'
        contact_details:
          $ref: '#/components/schemas/contact_details'
        pickup_notes:
          type: string
          minLength: 0
          description: >-
            Used by some carriers to give special instructions for a package
            pickup
        pickup_window:
          $ref: '#/components/schemas/pickup_window'
        pickup_windows:
          readOnly: true
          type: array
          description: >
            An array of available pickup windows. Carriers can return multiple
            times that they will pickup packages.
          items:
            allOf:
              - $ref: '#/components/schemas/pickup_windows'
    pickup_resource_id:
      title: pickup_resource_id
      type: string
      minLength: 4
      example: pik_3YcKU5zdtJuCqoeNwyqqbW
      description: Pickup Resource ID
    contact_details:
      title: contact_details
      type: object
      required:
        - name
        - email
        - phone
      properties:
        name:
          type: string
          minLength: 1
        email:
          allOf:
            - $ref: '#/components/schemas/email'
        phone:
          type: string
          minLength: 7
          description: Phone number associated
    pickup_window:
      title: pickup_window
      writeOnly: true
      type: object
      description: The desired time range for the package pickup.
      required:
        - start_at
        - end_at
      properties:
        start_at:
          allOf:
            - $ref: '#/components/schemas/date_time'
        end_at:
          allOf:
            - $ref: '#/components/schemas/date_time'
    pickup_windows:
      title: pickup_windows
      type: object
      properties:
        start_at:
          allOf:
            - $ref: '#/components/schemas/date_time'
        end_at:
          allOf:
            - $ref: '#/components/schemas/date_time'
    schedule_pickup_request_body:
      title: schedule_pickup_request_body
      description: A schedule pickup request body
      required:
        - contact_details
        - label_ids
        - pickup_window
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/pickup'
    schedule_pickup_response_body:
      title: schedule_pickup_response_body
      allOf:
        - $ref: '#/components/schemas/pickup'
        - $ref: '#/components/schemas/error_response_body'
    get_pickup_by_id_response_body:
      title: get_pickup_by_id_response_body
      allOf:
        - $ref: '#/components/schemas/pickup_response_body'
        - $ref: '#/components/schemas/error_response_body'
    pickup_response_body:
      title: pickup_response_body
      description: A pickup response body
      required:
        - pickup_id
        - label_ids
        - created_at
        - carrier_id
        - warehouse_id
        - pickup_address
        - contact_details
        - pickup_notes
        - pickup_window
        - confirmation_number
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/pickup'
    delete_pickup_by_id_response_body:
      title: delete_pickup_by_id_response_body
      allOf:
        - $ref: '#/components/schemas/error_response_body'
        - $ref: '#/components/schemas/delete_scheduled_pickup_response_body'
    delete_scheduled_pickup_response_body:
      title: delete_scheduled_pickup_response_body
      type: object
      description: A delete scheduled pickup response body
      additionalProperties: false
      required:
        - pickup_id
      properties:
        pickup_id:
          allOf:
            - $ref: '#/components/schemas/pickup_resource_id'
    calculate_rates_request_body:
      title: calculate_rates_request_body
      description: A rate shipment request body
      required:
        - shipment_id
        - shipment
      additionalProperties: false
      oneOf:
        - $ref: '#/components/schemas/shipment_id_request'
        - $ref: '#/components/schemas/rate_shipment_request'
      allOf:
        - $ref: '#/components/schemas/rate_request_options'
      properties:
        ship_to_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier service point where the shipment
            will be delivered by the carrier. This will take precedence over a
            shipment's ship to address.
          example: '614940'
        ship_from_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier drop off point where a merchant
            plans to deliver packages. This will take precedence over a
            shipment's ship from address.
          example: '614940'
    shipment_id_request:
      title: shipment_id_request
      type: object
      properties:
        shipment_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the shipment
    rate_shipment_request:
      title: rate_shipment_request
      type: object
      properties:
        shipment:
          allOf:
            - $ref: '#/components/schemas/address_validating_shipment'
          description: The shipment object
    address_validating_shipment:
      title: address_validating_shipment
      type: object
      description: >
        An address validating shipment.


        **Note**: The `carrier_id` and `service_code` fields are **required**
        within the `shipment` object when calling v1/rates. However, they are
        **optional** when rating if `rate_options` are provided, as
        `rate_options` will take precedence.
      required:
        - shipment_id
        - carrier_id
        - service_code
        - ship_to
        - ship_from
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/validate_shipment_fields'
        - $ref: '#/components/schemas/partial_shipment'
    validate_shipment_fields:
      title: validate_shipment_fields
      type: object
      properties:
        validate_address:
          default: no_validation
          allOf:
            - $ref: '#/components/schemas/validate_address'
    rate_request_options:
      title: rate_request_options
      type: object
      properties:
        rate_options:
          allOf:
            - $ref: '#/components/schemas/rate_request_body'
          description: The rate options
    rate_request_body:
      title: rate_request_body
      type: object
      description: A rate request body
      required:
        - carrier_ids
      additionalProperties: false
      properties:
        carrier_ids:
          type: array
          minItems: 1
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
            description: carrier ids
          description: Array of carrier ids to get rates for
        package_types:
          type: array
          items:
            type: string
            minLength: 1
        service_codes:
          type: array
          items:
            type: string
            minLength: 1
            description: Item Service Codes
        calculate_tax_amount:
          type: boolean
          description: Calculate the duties and tariffs for cross border shipments.
        preferred_currency:
          allOf:
            - $ref: '#/components/schemas/currency'
        is_return:
          type: boolean
          description: Indicate if it's a return shipment
        rate_type:
          type: string
          enum:
            - check
            - shipment
            - quick
          description: Indicates what type of rating to perform
    calculate_rates_response_body:
      title: calculate_rates_response_body
      description: A rate shipment response body
      required:
        - rate_response
        - shipment_id
        - ship_date
        - created_at
        - modified_at
        - shipment_status
        - return_to
        - insurance_provider
        - tags
        - packages
        - total_weight
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/partial_shipment'
        - $ref: '#/components/schemas/rate_response'
    rate_response:
      title: rate_response
      type: object
      additionalProperties: false
      properties:
        rate_response:
          allOf:
            - $ref: '#/components/schemas/rates_information'
          description: The rates response
    rates_information:
      title: rates_information
      type: object
      description: A rates information resource
      additionalProperties: false
      properties:
        rates:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/rate'
              - type: object
                properties:
                  rate_attributes:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/rate_attributes'
                    description: >-
                      Optional attributes that indicate the most profitable
                      rates
            description: Shipment Rates
          description: An array of shipment rates
        invalid_rates:
          type: array
          readOnly: true
          default: []
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/rate'
            description: Invalid Shipment Rate
          description: An array of invalid shipment rates
        rate_request_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the rate request
        shipment_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the shipment
        created_at:
          format: date-time
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: When the rate was created
        status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/rate_response_status'
        errors:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/error'
    rate:
      title: rate
      type: object
      description: A rate
      required:
        - rate_id
        - rate_type
        - carrier_id
        - shipping_amount
        - insurance_amount
        - confirmation_amount
        - other_amount
        - zone
        - package_type
        - guaranteed_service
        - negotiated_rate
        - service_type
        - service_code
        - trackable
        - carrier_code
        - carrier_nickname
        - carrier_friendly_name
        - validation_status
        - warning_messages
        - error_messages
      additionalProperties: false
      properties:
        rate_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the rate
        rate_type:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/rate_type'
        carrier_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the carrier
        shipping_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: >-
            The shipping amount. Should be added with confirmation_amount,
            insurance_amount and other_amount to calculate the total purchase
            price.
        insurance_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: >-
            The insurance amount.  Should be added with shipping_amount,
            confirmation_amount and other_amount to calculate the total purchase
            price.
        confirmation_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: >-
            The confirmation amount.  Should be added with shipping_amount,
            insurance_amount and other_amount to calculate the total purchase
            price.
        other_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: >-
            Any other charges associated with this rate.  Should be added with
            shipping_amount, insurance_amount and confirmation_amount to
            calculate the total purchase price.
        requested_comparison_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The total shipping cost for the specified comparison_rate_type.
        tax_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: >-
            Tariff and additional taxes associated with an international
            shipment.
        rate_details:
          readOnly: true
          description: >
            A list of rate details that are associated with this rate. This is
            useful for displaying a breakdown of the rate to the user.
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/rate_detail'
        zone:
          type: integer
          format: int32
          nullable: true
          readOnly: true
          minimum: 0
          example: 6
          description: >
            Certain carriers base [their
            rates](https://blog.stamps.com/2017/09/08/usps-postal-zones/) off of

            custom zones that vary depending upon the ship_to and ship_from
            location
        package_type:
          type: string
          nullable: true
          readOnly: true
          minLength: 1
          example: package
          description: package type that this rate was estimated for
        delivery_days:
          type: integer
          format: int32
          nullable: true
          readOnly: true
          minimum: 1
          example: 5
          description: >
            The number of days estimated for delivery, this will show the
            _actual_ delivery

            time if for example, the package gets shipped on a Friday
        guaranteed_service:
          type: boolean
          readOnly: true
          description: Indicates if the rate is guaranteed.
        estimated_delivery_date:
          type: string
          nullable: true
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date'
        carrier_delivery_days:
          type: string
          readOnly: true
          minLength: 1
          description: The carrier delivery days
        ship_date:
          type: string
          format: date-time
          readOnly: true
          minLength: 1
          description: ship date
        negotiated_rate:
          type: boolean
          readOnly: true
          description: Indicates if the rates been negotiated
        service_type:
          type: string
          readOnly: true
          minLength: 1
          description: service type
        service_code:
          type: string
          readOnly: true
          minLength: 1
          description: service code for the rate
        trackable:
          type: boolean
          readOnly: true
          description: Indicates if rate is trackable
        carrier_code:
          type: string
          readOnly: true
          minLength: 1
          description: carrier code
        carrier_nickname:
          type: string
          readOnly: true
          minLength: 1
          description: carrier nickname
        carrier_friendly_name:
          type: string
          readOnly: true
          minLength: 1
          description: carrier friendly name
        validation_status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/validation_status'
        warning_messages:
          type: array
          readOnly: true
          minItems: 0
          items:
            type: string
            readOnly: true
            minLength: 0
            description: warning message
          description: The warning messages
        error_messages:
          type: array
          readOnly: true
          minItems: 0
          items:
            type: string
            readOnly: true
            minLength: 0
            description: error message
          description: The error messages
    rate_type:
      title: rate_type
      type: string
      enum:
        - check
        - shipment
      description: The possible rate type values
    validation_status:
      title: validation_status
      type: string
      enum:
        - valid
        - invalid
        - has_warnings
        - unknown
      description: The possible validation status values
    rate_response_status:
      title: rate_response_status
      type: string
      enum:
        - working
        - completed
        - partial
        - error
      description: The possible rate response status values
    compare_bulk_rates_request_body:
      title: compare_bulk_rates_request_body
      description: A rate shipments request body
      required:
        - rate_options
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/rate_request_rate_options'
      oneOf:
        - $ref: '#/components/schemas/rate_request_by_shipment_ids'
        - $ref: '#/components/schemas/rate_request_by_shipments'
      properties:
        ship_to_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier service point where the shipment
            will be delivered by the carrier. This will take precedence over a
            shipment's ship to address.
          example: '614940'
        ship_from_service_point_id:
          nullable: true
          type: string
          description: >-
            A unique identifier for a carrier drop off point where a merchant
            plans to deliver packages. This will take precedence over a
            shipment's ship from address.
          example: '614940'
    rate_request_rate_options:
      title: rate_request_rate_options
      type: object
      properties:
        rate_options:
          allOf:
            - $ref: '#/components/schemas/rate_request_body'
          description: The rate options
    rate_request_by_shipment_ids:
      title: rate_request_by_shipment_ids
      type: object
      required:
        - shipment_ids
      properties:
        shipment_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
            description: shipment ids
          description: The array of shipment IDs
    rate_request_by_shipments:
      title: rate_request_by_shipments
      type: object
      required:
        - shipments
      properties:
        shipments:
          type: array
          minItems: 1
          items:
            allOf:
              - $ref: '#/components/schemas/address_validating_shipment'
            description: The shipment to get a bulk rate estimate for
          description: The array of shipments to get bulk rate estimates for
    compare_bulk_rates_response_body:
      title: compare_bulk_rates_response_body
      type: array
      description: A bulk rate response body
      items:
        $ref: '#/components/schemas/bulk_rate'
    bulk_rate:
      title: bulk_rate
      type: object
      description: A bulk rate
      required:
        - rate_request_id
        - shipment_id
        - created_at
        - status
        - errors
      additionalProperties: false
      properties:
        rate_request_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the rate request
        shipment_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the shipment
        created_at:
          format: date-time
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
        status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/rate_response_status'
        errors:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/error'
            description: An error that occurred while retrieving the bulk rate
          description: An array of errors that were returned while retrieving the bulk rate
    estimate_rates_request_body:
      title: estimate_rates_request_body
      description: A rate estimate request body
      required:
        - from_country_code
        - from_postal_code
        - from_city_locality
        - from_state_province
        - to_country_code
        - to_postal_code
        - to_city_locality
        - to_state_province
        - weight
        - ship_date
      additionalProperties: false
      oneOf:
        - $ref: '#/components/schemas/rate_estimate_by_carrier_id'
        - $ref: '#/components/schemas/rate_estimate_by_carrier_ids'
      allOf:
        - $ref: '#/components/schemas/rate_estimate_options'
    rate_estimate_by_carrier_id:
      title: rate_estimate_by_carrier_id
      type: object
      properties:
        carrier_id:
          deprecated: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the carrier
    rate_estimate_by_carrier_ids:
      title: rate_estimate_by_carrier_ids
      type: object
      properties:
        carrier_ids:
          type: array
          minItems: 1
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
            description: carrier id
          description: Array of Carrier Ids
    rate_estimate_options:
      title: rate_estimate_options
      type: object
      properties:
        from_country_code:
          allOf:
            - $ref: '#/components/schemas/country_code'
        from_postal_code:
          allOf:
            - $ref: '#/components/schemas/postal_code'
        from_city_locality:
          type: string
          minLength: 1
          example: Austin
          description: from postal code
        from_state_province:
          type: string
          minLength: 1
          example: Austin
          description: From state province
        to_country_code:
          allOf:
            - $ref: '#/components/schemas/country_code'
        to_postal_code:
          allOf:
            - $ref: '#/components/schemas/postal_code'
        to_city_locality:
          type: string
          minLength: 1
          example: Austin
          description: The city locality the package is being shipped to
        to_state_province:
          type: string
          minLength: 1
          example: Houston
          description: To state province
        weight:
          allOf:
            - $ref: '#/components/schemas/weight'
          description: The weight of the package
        dimensions:
          allOf:
            - $ref: '#/components/schemas/dimensions'
          description: The dimensions of the package
        confirmation:
          allOf:
            - $ref: '#/components/schemas/delivery_confirmation'
        address_residential_indicator:
          allOf:
            - $ref: '#/components/schemas/address_residential_indicator'
        ship_date:
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: ship date
    estimate_rates_response_body:
      title: estimate_rates_response_body
      type: array
      description: A rate estimate response body
      items:
        allOf:
          - $ref: '#/components/schemas/rate_estimate'
    rate_estimate:
      title: rate_estimate
      type: object
      description: A rate estimate
      required:
        - rate_type
        - carrier_id
        - shipping_amount
        - insurance_amount
        - confirmation_amount
        - other_amount
        - zone
        - package_type
        - guaranteed_service
        - negotiated_rate
        - service_type
        - service_code
        - trackable
        - carrier_code
        - carrier_nickname
        - carrier_friendly_name
        - validation_status
        - warning_messages
        - error_messages
      additionalProperties: false
      properties:
        rate_type:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/rate_type'
        carrier_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the carrier
        shipping_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The shipping amount
        insurance_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The insurance amount
        confirmation_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The confirmation amount
        other_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: Any other charges associated with this rate
        tax_amount:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: >-
            Tariff and additional taxes associated with an international
            shipment.
        zone:
          type: integer
          format: int32
          nullable: true
          readOnly: true
          minimum: 0
          example: 6
          description: >
            Certain carriers base [their
            rates](https://blog.stamps.com/2017/09/08/usps-postal-zones/) off of

            custom zones that vary depending upon the ship_to and ship_from
            location
        package_type:
          type: string
          nullable: true
          readOnly: true
          minLength: 1
          example: package
          description: package type that this rate was estimated for
        delivery_days:
          type: integer
          format: int32
          nullable: true
          readOnly: true
          minimum: 1
          example: 5
          description: >
            The number of days estimated for delivery, this will show the
            _actual_ delivery

            time if for example, the package gets shipped on a Friday
        guaranteed_service:
          type: boolean
          readOnly: true
          description: Indicates if the rate is guaranteed.
        estimated_delivery_date:
          type: string
          nullable: true
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date'
        carrier_delivery_days:
          type: string
          readOnly: true
          minLength: 1
          description: The carrier delivery days
        ship_date:
          type: string
          format: date-time
          readOnly: true
          minLength: 1
          description: ship date
        negotiated_rate:
          type: boolean
          readOnly: true
          description: Indicates if the rates been negotiated
        service_type:
          type: string
          readOnly: true
          minLength: 1
          description: service type
        service_code:
          type: string
          readOnly: true
          minLength: 1
          description: service code for the rate
        trackable:
          type: boolean
          readOnly: true
          description: Indicates if rate is trackable
        carrier_code:
          type: string
          readOnly: true
          minLength: 1
          description: >-
            A shipping carrier, such as `fedex`, `dhl_express`, `stamps_com`,
            etc.
        carrier_nickname:
          type: string
          readOnly: true
          minLength: 1
          description: carrier nickname
        carrier_friendly_name:
          type: string
          readOnly: true
          minLength: 1
          description: carrier friendly name
        validation_status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/validation_status'
        warning_messages:
          type: array
          readOnly: true
          minItems: 0
          items:
            type: string
            readOnly: true
            minLength: 0
            description: warning message
          description: The warning messages
        error_messages:
          type: array
          readOnly: true
          minItems: 0
          items:
            type: string
            readOnly: true
            minLength: 0
            description: error message
          description: The error messages
        rate_attributes:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/rate_attributes'
          description: Optional attributes that indicate the most profitable rates
    get_rate_by_id_response_body:
      title: get_rate_by_id_response_body
      description: A rate response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/rates_information'
    get_service_points_request:
      title: get_service_points_request
      oneOf:
        - $ref: '#/components/schemas/get_service_points_request_body'
    get_service_points_request_body:
      title: get_service_points_request_body
      type: object
      description: >-
        A get service points request body. Caller must provide exactly one of
        address_query, address, or lat / long pair.
      required:
        - providers
      properties:
        address_query:
          type: string
          description: Unstructured text to search for service points by.
          example: 177A Bleecker Street New York
        address:
          type: object
          description: Structured address to search by.
          required:
            - country_code
          properties:
            address_line1:
              type: string
              example: 1999 Bishop Grandin Blvd.
              description: >-
                The first line of the street address. For some addresses, this
                may be the only line. Other addresses may require 2 or 3 lines.
            address_line2:
              type: string
            address_line3:
              type: string
            city_locality:
              type: string
              description: The name of the city or locality
            state_province:
              type: string
              description: >-
                The state or province. For some countries (including the U.S.)
                only abbreviations are allowed. Other countries allow the full
                name or abbreviation.
            postal_code:
              allOf:
                - $ref: '#/components/schemas/postal_code'
            country_code:
              allOf:
                - $ref: '#/components/schemas/country_code'
        providers:
          type: array
          description: An array of shipping service providers and service codes
          items:
            type: object
            properties:
              carrier_id:
                type: string
                example: se-123456
                description: Uniquely identifies a carrier connection
              service_code:
                type: array
                items:
                  type: string
                  example: chronoclassic
                  description: Uniquely identifies a shipping service
        lat:
          format: double
          type: number
          example: 48.874518928233094
          description: >-
            The latitude of the point. Represented as signed degrees. Required
            if long is provided. http://www.geomidpoint.com/latlon.html
        long:
          format: double
          type: number
          example: 2.3591775711639404
          description: >-
            The longitude of the point. Represented as signed degrees. Required
            if lat is provided. http://www.geomidpoint.com/latlon.html
        radius:
          format: int32
          type: integer
          example: 500
          description: Search radius in kilometers
        max_results:
          format: int32
          type: integer
          example: 25
          description: The maximum number of service points to return
        shipment:
          type: object
          description: Shipment information to be used for service point selection
          properties:
            total_weight:
              allOf:
                - $ref: '#/components/schemas/weight'
              description: Shipment total weight
            packages:
              type: array
              description: An array of package dimensions
              items:
                type: object
                properties:
                  dimensions:
                    allOf:
                      - $ref: '#/components/schemas/dimensions'
                    description: The package dimensions
    list_service_points_response_body:
      title: list_service_points_response_body
      type: object
      description: A list service points response body
      properties:
        lat:
          format: double
          type: number
          example: 48.842608
          description: >-
            The latitude of the point. Represented as signed degrees. Required
            if long is provided. http://www.geomidpoint.com/latlon.html
        long:
          format: double
          type: number
          example: 0.032875
          description: >-
            The longitude of the point. Represented as signed degrees. Required
            if lat is provided. http://www.geomidpoint.com/latlon.html
        service_points:
          type: array
          items:
            type: object
            properties:
              carrier_code:
                allOf:
                  - $ref: '#/components/schemas/carrier_code'
              service_codes:
                type: array
                items:
                  type: string
                  example: chronoclassic
                  description: A shipping carrier service code.
              service_point_id:
                type: string
                example: '614940'
                description: A unique identifier for a carrier drop off point.
              company_name:
                type: string
                example: My fancy company name
                description: >-
                  If this is a business address, then the company name should be
                  specified here.
              address_line1:
                type: string
                example: PLACE DU CANADA
                description: >-
                  The first line of the street address.  For some addresses,
                  this may be the only line.  Other addresses may require 2 or 3
                  lines.
              city_locality:
                type: string
                example: TRUN
                description: The name of the city or locality
              state_province:
                type: string
                example: TRUN
                description: >-
                  The state or province. For some countries (including the U.S.)
                  only abbreviations are allowed. Other countries allow the full
                  name or abbreviation.
              postal_code:
                allOf:
                  - $ref: '#/components/schemas/postal_code'
              country_code:
                allOf:
                  - $ref: '#/components/schemas/country_code'
              phone_number:
                type: string
                example: 555-555-5555
                description: Phone number associated
              lat:
                format: double
                type: number
                example: 48.842608
                description: >-
                  The latitude of the point. Represented as signed degrees.
                  Required if long is provided.
                  http://www.geomidpoint.com/latlon.html
              long:
                format: double
                type: number
                example: 0.032875
                description: >-
                  The longitude of the point. Represented as signed degrees.
                  Required if lat is provided.
                  http://www.geomidpoint.com/latlon.html
              distance_in_meters:
                format: double
                type: number
                example: 728.9959308847579
                description: Distance in meters
              hours_of_operation:
                type: object
                description: Hours of operation
                properties:
                  monday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                          description: Opening time
                        close:
                          type: string
                          example: '12:00'
                          description: Closing time
                  tuesday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                          description: Opening time
                        close:
                          type: string
                          example: '12:00'
                          description: Closing time
                  wednesday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                          description: Opening time
                        close:
                          type: string
                          example: '12:00'
                          description: Closing time
                  thursday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                          description: Opening time
                        close:
                          type: string
                          example: '12:00'
                          description: Closing time
                  friday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                          description: Opening time
                        close:
                          type: string
                          example: '12:00'
                          description: Closing time
                  saturday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                          description: Opening time
                        close:
                          type: string
                          example: '12:00'
                          description: Closing time
                  sunday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                          description: Opening time
                        close:
                          type: string
                          example: '12:00'
                          description: Closing time
              features:
                type: array
                description: Service features
                items:
                  type: string
                  enum:
                    - drop_off_point
                    - pickup_point
                    - print_services
                    - after_hours_locker
                    - after_hours_dropbox
              type:
                type: string
                description: Service point type
                default: pudo
                enum:
                  - pudo
                  - locker
        errors:
          type: array
          readOnly: true
          items:
            allOf:
              - $ref: '#/components/schemas/error'
          description: The errors associated with the failed API call
    get_service_point_by_id_response_body:
      title: get_service_point_by_id_response_body
      type: object
      description: A get service point by ID response body
      properties:
        service_point:
          type: object
          properties:
            carrier_code:
              allOf:
                - $ref: '#/components/schemas/carrier_code'
            service_codes:
              type: array
              items:
                type: string
                description: A shipping carrier service code.
            service_point_id:
              type: string
              example: '614940'
              description: A unique identifier for a carrier drop off point.
            company_name:
              type: string
              example: My fancy company name
              description: >-
                If this is a business address, then the company name should be
                specified here.
            address_line1:
              type: string
              example: PLACE DU CANADA
              description: >-
                The first line of the street address.  For some addresses, this
                may be the only line.  Other addresses may require 2 or 3 lines.
            city_locality:
              type: string
              example: TRUN
              description: The name of the city or locality
            state_province:
              type: string
              example: TRUN
              description: >-
                The state or province. For some countries (including the U.S.)
                only abbreviations are allowed. Other countries allow the full
                name or abbreviation.
            postal_code:
              allOf:
                - $ref: '#/components/schemas/postal_code'
            country_code:
              allOf:
                - $ref: '#/components/schemas/country_code'
            phone_number:
              type: string
              example: 555-555-5555
              description: Phone number associated
            lat:
              format: double
              type: number
              example: 48.842608
              description: >-
                The latitude of the point. Represented as signed degrees.
                Required if long is provided.
                http://www.geomidpoint.com/latlon.html
            long:
              format: double
              type: number
              example: 0.032875
              description: >-
                The longitude of the point. Represented as signed degrees.
                Required if lat is provided.
                http://www.geomidpoint.com/latlon.html
            hours_of_operation:
              type: object
              description: Hours of operation
              properties:
                monday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                        description: Opening time
                      close:
                        type: string
                        example: '12:00'
                        description: Closing time
                tuesday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                        description: Opening time
                      close:
                        type: string
                        example: '12:00'
                        description: Closing time
                wednesday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                        description: Opening time
                      close:
                        type: string
                        example: '12:00'
                        description: Closing time
                thursday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                        description: Opening time
                      close:
                        type: string
                        example: '12:00'
                        description: Closing time
                friday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                        description: Opening time
                      close:
                        type: string
                        example: '12:00'
                        description: Closing time
                saturday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                        description: Opening time
                      close:
                        type: string
                        example: '12:00'
                        description: Closing time
                sunday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                        description: Opening time
                      close:
                        type: string
                        example: '12:00'
                        description: Closing time
            features:
              type: array
              description: Service features
              items:
                type: string
                enum:
                  - drop_off_point
                  - pickup_point
                  - print_services
                  - after_hours_locker
                  - after_hours_dropbox
            type:
              type: string
              description: Service point type
              default: pudo
              enum:
                - pudo
                - locker
    shipments_sort_by:
      title: shipments_sort_by
      type: string
      enum:
        - modified_at
        - created_at
      description: The possible shipments sort by values
    list_shipments_response_body:
      title: list_shipments_response_body
      type: object
      description: A list shipment response body
      required:
        - shipments
        - total
        - page
        - pages
        - links
      additionalProperties: false
      properties:
        shipments:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/shipment'
            description: A shipment object
          description: The list of shipments returned by the api call
        total:
          type: integer
          format: int64
          readOnly: true
          minimum: 0
          example: 1990
          description: Total number of shipments returned by the api call
        page:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          example: 1
        pages:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
        links:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/pagination_link'
    create_shipments_request_body:
      title: create_shipments_request_body
      type: object
      description: A create shipments request body
      required:
        - shipments
      additionalProperties: false
      properties:
        shipments:
          type: array
          minItems: 1
          items:
            allOf:
              - $ref: '#/components/schemas/address_validating_shipment'
          description: An array of shipments to be created.
    create_shipments_response_body:
      title: create_shipments_response_body
      type: object
      description: A create shipments response body
      required:
        - has_errors
        - shipments
      additionalProperties: false
      properties:
        has_errors:
          type: boolean
          default: false
          description: Indicates if errors occured while creating the shipments
        shipments:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/create_and_validate_shipment'
            description: The shipment that was created.
          description: An array of shipments that were created.
    create_and_validate_shipment:
      title: create_and_validate_shipment
      description: A create and validate shipment resource
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/partial_shipment'
        - $ref: '#/components/schemas/create_shipment_response_body_fields'
    create_shipment_response_body_fields:
      title: create_shipment_response_body_fields
      type: object
      properties:
        errors:
          type: array
          deprecated: true
          items:
            type: string
            minLength: 1
            example: Parameter value '100000000.00' is out of range.
            description: An error that occurred while creating a shipment.
          description: An array of errors that occurred while creating shipment.
          readOnly: true
        address_validation:
          allOf:
            - $ref: '#/components/schemas/address_validation_result'
          description: The address validation
    get_shipment_by_external_id_response_body:
      title: get_shipment_by_external_id_response_body
      description: A get shipment by external id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/shipment'
    parse_shipment_request_body:
      title: parse_shipment_request_body
      type: object
      description: >
        The only required field is `text`, which is the text to be parsed. You
        can optionally also provide a `shipment` containing any already-known
        values. For example, you probably already know the `ship_from` address,
        and you may also already know what carrier and service you want to use.
      required:
        - text
      additionalProperties: false
      properties:
        text:
          type: string
          minLength: 1
          example: >
            I have a 4oz package that's 5x10x14in, and I need to ship it to
            Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652.
            Please send it via USPS first class and require an adult signature.
            It also needs to be insured for $400.
          description: The unstructured text that contains shipping-related entities
        shipment:
          allOf:
            - $ref: '#/components/schemas/partial_shipment'
          description: >
            You can optionally provide a `shipment` object containing any
            already-known values. For example, you probably already know the
            `ship_from` address, and you may also already know what carrier and
            service you want to use.
    parse_shipment_response_body:
      title: parse_shipment_response_body
      type: object
      description: >
        The parsed shipment, as well as a confidence score and a list of all the
        shipping entities that were recognized in the text.
      required:
        - score
        - shipment
        - entities
      additionalProperties: false
      properties:
        score:
          type: number
          format: double
          minimum: 0
          maximum: 1
          description: >
            A confidence score between zero and one that indicates how certain
            the API is that it understood the text.
        shipment:
          allOf:
            - $ref: '#/components/schemas/partial_shipment'
          description: >
            The parsed shipment.  This shipment may not be complete, depending
            on how much information was included in the text and how confident
            the API is about each recognized entity.


            > **Note:** The shipment-recognition API does not currently perform
            any validation of the parsed addresses, so we recommend that you use
            the address-validation API to ensure that the addresses are correct.
        entities:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/recognized_entity'
          description: >
            All of the entities that were recognized in the text. An "entity" is
            a single piece of data, such as a city, a postal code, a carrier
            name, or a package weight.  Each entity includes the original text
            and the parsed value.
    get_shipment_by_id_response_body:
      title: get_shipment_by_id_response_body
      description: A get shipment by id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/shipment'
    update_shipment_request_body:
      title: update_shipment_request_body
      description: An update shipment request body
      required:
        - ship_to
        - ship_from
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/partial_shipment'
        - $ref: '#/components/schemas/update_shipment_fields'
    update_shipment_fields:
      title: update_shipment_fields
      type: object
      properties:
        validate_address:
          default: no_validation
          allOf:
            - $ref: '#/components/schemas/validate_address'
    update_shipment_response_body:
      title: update_shipment_response_body
      description: An update shipment response body
      required:
        - errors
        - address_validation
        - shipment_id
        - carrier_id
        - service_code
        - ship_date
        - created_at
        - shipment_status
        - ship_to
        - ship_from
        - return_to
        - customs
        - advanced_options
        - insurance_provider
        - tags
        - packages
        - total_weight
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/create_and_validate_shipment'
    assign_user_request_body:
      title: assign_user_request_body
      type: object
      description: A request body for assigning a user to shipments
      required:
        - shipment_ids
        - user_id
      additionalProperties: false
      properties:
        shipment_ids:
          type: array
          minItems: 1
          maxItems: 500
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
          description: Array of shipment IDs to assign the user to
          example:
            - se-202902255
            - se-202902256
        user_id:
          type: string
          format: uuid
          description: The ID of the user to assign to the shipments
          example: a2df9fa5-b7ee-467f-be4e-9c660542c187
    assign_user_response_body:
      title: assign_user_response_body
      type: object
      description: A response body for assigning a user to shipments
      additionalProperties: false
      properties:
        shipment_ids:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/se_id'
          description: Array of shipment IDs that were assigned to the user
          example:
            - se-202902255
            - se-202902256
        user_id:
          type: string
          format: uuid
          description: The ID of the user assigned to the shipments
          example: a2df9fa5-b7ee-467f-be4e-9c660542c187
    list_shipment_rates_response_body:
      title: list_shipment_rates_response_body
      description: A list shipment rates response body
      required:
        - rates
        - invalid_rates
        - rate_request_id
        - shipment_id
        - created_at
        - status
        - errors
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/rates_information'
    update_shipments_tags_request_body:
      title: update_shipments_tags_request_body
      description: A request body with shipments and tags
      allOf:
        - $ref: '#/components/schemas/update_shipments_tags'
    update_shipments_tags:
      title: update_shipments_tags
      type: object
      properties:
        shipments_tags:
          type: array
          items:
            type: object
            properties:
              shipment_id:
                type: string
              tags:
                type: array
                items:
                  type: string
      example:
        shipments_tags:
          - shipment_id: se-1014296
            tags:
              - Fragile
              - International
          - shipment_id: se-1014297
            tags:
              - Fragile
              - International
    tag_shipment_response_body:
      title: tag_shipment_response_body
      type: object
      description: Get shipment tags response body
      required:
        - tags
      additionalProperties: false
      properties:
        tags:
          type: array
          items:
            $ref: '#/components/schemas/tag_name'
    tag_name:
      title: tag_name
      type: string
      minLength: 1
      example: Fragile
      description: >
        Tags are arbitrary strings that you can use to categorize shipments. For
        example, you may want to use tags to distinguish between domestic and
        international shipments, or between insured and uninsured shipments.  Or
        maybe you want to create a tag for each of your customers so you can
        easily retrieve every shipment for a customer.
    list_tags_response_body:
      title: list_tags_response_body
      type: object
      description: Response body from a successful GET /tags API call
      additionalProperties: false
      properties:
        tags:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/tag'
          description: The array of tags returned by the API call
    create_tag_request_body:
      title: create_tag_request_body
      type: object
      description: A create tag request body
      required:
        - name
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          example: Fragile
          description: The tag name.
        color:
          type: string
          minLength: 1
          example: '#FF0000'
          description: A hex-coded string identifying the color of the tag.
    create_tag_response_body:
      title: create_tag_response_body
      description: Response body for creating tags
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/tag'
    redirect:
      title: redirect
      type: string
      enum:
        - shipengine-dashboard
      description: The resource to return a redirect URL to.
    tokens_get_ephemeral_token_response_body.yaml:
      title: tokens_get_ephemeral_token_response_body.yaml
      type: object
      properties:
        token:
          type: string
          description: The requested token that expires in 10 seconds.
        redirect_url:
          type: string
          description: The redirect url formatted with the requested token.
    get_tracking_log_response_body:
      title: get_tracking_log_response_body
      description: A get tracking log response body
      required:
        - tracking_number
        - tracking_url
        - status_code
        - carrier_code
        - carrier_id
        - carrier_detail_code
        - carrier_status_code
        - events
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/tracking_information'
    list_warehouses_response_body:
      title: list_warehouses_response_body
      type: object
      description: A warehouse list response body
      required:
        - warehouses
      additionalProperties: false
      properties:
        warehouses:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/warehouse'
          description: The array of warehouses returned by the API call
    warehouse:
      title: warehouse
      type: object
      description: A warehouse
      additionalProperties: false
      properties:
        warehouse_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the warehouse
        is_default:
          nullable: true
          type: boolean
          default: false
          description: Designates which single warehouse is the default on the account
        name:
          type: string
          minLength: 1
          example: Zero Cool HQ
          description: Name of the warehouse
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2019-06-25T18:12:35.583Z'
          minLength: 1
          description: Timestamp that indicates when the warehouse was created
        origin_address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The origin address of the warehouse
        return_address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The return address associated with the warehouse
    create_warehouse_request_body:
      title: create_warehouse_request_body
      description: A create warehouse request body
      required:
        - name
        - origin_address
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/warehouse'
    create_warehouse_response_body:
      title: create_warehouse_response_body
      description: A create warehouse response body
      required:
        - warehouse_id
        - name
        - created_at
        - origin_address
        - return_address
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/warehouse'
    get_warehouse_by_id_response_body:
      title: get_warehouse_by_id_response_body
      description: A get warehouse by id response body
      required:
        - warehouse_id
        - name
        - created_at
        - origin_address
        - return_address
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/warehouse'
    update_warehouse_request_body:
      title: update_warehouse_request_body
      description: An update warehouse request body
      required:
        - name
        - origin_address
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/warehouse'
    update_warehouse_settings_request_body:
      title: update_warehouse_settings_request_body
      type: object
      description: An update warehouse settings request body
      properties:
        is_default:
          type: boolean
          nullable: true
          description: The default property on the warehouse.
          example: true
      additionalProperties: false
    manufacturer_product_identifier_type:
      title: manufacturer_product_identifier_type
      type: string
      enum:
        - undefined
        - gtin
        - ean
        - isbn
        - upc
        - mpn
        - sku
      description: >-
        The type of manufacturer product identifier. GTIN (Global Trade Item
        Number), EAN (European Article Number), ISBN (International Standard
        Book Number), UPC (Universal Product Code), MPN (Manufacturer Part
        Number), SKU (Stock Keeping Unit). Use `undefined` when the specific
        identifier type is not defined in this list.
    cpsc_certificate:
      title: cpsc_certificate
      type: object
      description: >-
        A US Consumer Product Safety Commission (CPSC) eFiling certificate
        associated with a product in the shipment.
      additionalProperties: false
      properties:
        certifier_id:
          type: string
          maxLength: 50
          description: Unique identifier assigned to the certifier by the CPSC.
          example: CERT-12345
        certificate_version_id:
          type: string
          maxLength: 50
          description: The version identifier of the CPSC certificate.
          example: v1.0
    checkout_rates_service_selection:
      title: checkout_rates_service_selection
      type: object
      description: >
        A carrier and service pairing used by `live_rate` and `local_delivery`
        delivery options. Both fields are required for each entry.
      additionalProperties: false
      required:
        - carrier_id
        - service_code
      properties:
        carrier_id:
          type: string
          pattern: ^se-[0-9]+$
          example: se-1234567
          description: >
            The ID of a carrier connected to your account, in the format `se-`
            followed by digits (for example, `se-1234567`). A value that does
            not match this format is rejected with a validation error, and a
            well-formed ID that is not connected to your account is rejected as
            an invalid identifier.
        service_code:
          type: string
          minLength: 1
          example: usps_priority_mail
          description: >
            The service code of the carrier service to rate (for example,
            `usps_priority_mail`). Required for each service; a service code
            that is not available for the carrier is rejected as an invalid
            identifier.
    checkout_rates_dimensions_by_weight:
      title: checkout_rates_dimensions_by_weight
      type: object
      description: >
        A default package size to apply to carts whose total weight is at or
        below `max_weight`. Used when the configuration calculates live rates
        without explicit package dimensions.
      additionalProperties: false
      properties:
        max_weight:
          allOf:
            - $ref: '#/components/schemas/weight'
          description: The upper weight bound this default package applies to.
        default_dimensions:
          allOf:
            - $ref: '#/components/schemas/dimensions'
          description: >-
            The default package dimensions to use for carts within this weight
            bound.
    checkout_rates_shared_settings:
      title: checkout_rates_shared_settings
      type: object
      description: >
        Settings shared by every delivery option in a configuration, controlling
        how live rates are calculated.
      additionalProperties: false
      properties:
        calculation_method:
          type: string
          enum:
            - by_volume
            - skip_dimensions
          example: by_volume
          description: >
            How package dimensions are determined when calculating live rates.
            `by_volume` derives a package size from the cart; `skip_dimensions`
            rates without dimensions.
        dimensions_by_weight:
          type: array
          items:
            $ref: '#/components/schemas/checkout_rates_dimensions_by_weight'
          description: Default package dimensions applied to carts by weight bound.
    checkout_rates_option_request_body:
      title: checkout_rates_option_request_body
      type: object
      description: >
        The configuration of a single delivery option. The fields that apply
        depend on `type`:


        - `live_rate` and `local_delivery` use `services` (and may apply
        `fee_mode`/`fee_percentage`); `live_rate` may also define a
        `fallback_mode`.

        - `flat_rate` uses `amount`/`currency`.

        - `free` requires no additional fields.
      additionalProperties: false
      required:
        - name
        - type
      properties:
        name:
          type: string
          minLength: 1
          example: Standard Shipping
          description: >-
            The display name of the delivery option. Must be unique within the
            configuration.
        type:
          type: string
          enum:
            - live_rate
            - flat_rate
            - free
            - local_delivery
          example: live_rate
          description: The kind of delivery option.
        services:
          type: array
          items:
            $ref: '#/components/schemas/checkout_rates_service_selection'
          description: >-
            The carrier/service pairings to rate. Applies to `live_rate` and
            `local_delivery` options.
        fee_mode:
          type: string
          enum:
            - add
            - subtract
          example: add
          description: >
            Whether the fee defined by `fee_percentage` is added to or
            subtracted from the carrier rate. Omit for a pass-through rate.
        fee_percentage:
          type: number
          example: 10
          description: >-
            The percentage of the carrier rate to add or subtract, according to
            `fee_mode`.
        sort_index:
          type: integer
          example: 0
          description: >-
            The position of this option relative to the others in the
            configuration, ascending.
        fallback_mode:
          type: string
          enum:
            - dont_show
            - flat_rate
            - cart_percentage
          example: flat_rate
          description: >
            What to show when live rates cannot be retrieved. `dont_show` hides
            the option; `flat_rate` shows
            `fallback_rate_amount`/`fallback_rate_currency`; `cart_percentage`
            shows `fallback_percentage` of the cart total.
        fallback_rate_amount:
          type: number
          example: 5
          description: The fixed fallback price, when `fallback_mode` is `flat_rate`.
        fallback_rate_currency:
          type: string
          example: USD
          description: The currency of `fallback_rate_amount`.
        fallback_percentage:
          type: number
          example: 5
          description: >-
            The percentage of the cart total to charge, when `fallback_mode` is
            `cart_percentage`.
        amount:
          type: number
          example: 4.99
          description: The fixed price for a `flat_rate` option.
        currency:
          type: string
          example: USD
          description: The currency of `amount`.
    checkout_rates_option_response_body:
      title: checkout_rates_option_response_body
      type: object
      description: A delivery option belonging to a checkout rates configuration.
      additionalProperties: false
      properties:
        option_id:
          type: integer
          readOnly: true
          example: 100001
          description: The unique identifier of the delivery option.
        config_id:
          type: string
          readOnly: true
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          description: The identifier of the configuration this option belongs to.
        name:
          type: string
          example: Standard Shipping
          description: The display name of the delivery option.
        type:
          type: string
          enum:
            - live_rate
            - flat_rate
            - free
            - local_delivery
          example: live_rate
          description: The kind of delivery option.
        services:
          type: array
          items:
            $ref: '#/components/schemas/checkout_rates_service_selection'
          description: The carrier/service pairings rated by this option, when applicable.
        fee_mode:
          type: string
          enum:
            - add
            - subtract
          example: add
          description: >-
            Whether `fee_percentage` is added to or subtracted from the carrier
            rate.
        fee_percentage:
          type: number
          example: 10
          description: >-
            The percentage of the carrier rate added or subtracted, according to
            `fee_mode`.
        sort_index:
          type: integer
          example: 0
          description: >-
            The position of this option relative to the others in the
            configuration, ascending.
        fallback_mode:
          type: string
          enum:
            - dont_show
            - flat_rate
            - cart_percentage
          example: flat_rate
          description: What is shown when live rates cannot be retrieved.
        fallback_rate_amount:
          type: number
          example: 5
          description: The fixed fallback price, when `fallback_mode` is `flat_rate`.
        fallback_rate_currency:
          type: string
          example: USD
          description: The currency of `fallback_rate_amount`.
        fallback_percentage:
          type: number
          example: 5
          description: >-
            The percentage of the cart total charged, when `fallback_mode` is
            `cart_percentage`.
        amount:
          type: number
          example: 0
          description: The fixed price for a `flat_rate` option.
        currency:
          type: string
          example: USD
          description: The currency of `amount`.
        is_active:
          type: boolean
          readOnly: true
          example: true
          description: Whether the option is active and shown at checkout.
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2026-05-15T18:30:00Z'
          description: When the option was created.
    create_checkout_rates_config_request_body:
      title: create_checkout_rates_config_request_body
      type: object
      description: >-
        The configuration to create, including its initial delivery options and
        shared settings.
      additionalProperties: false
      properties:
        options:
          type: array
          items:
            $ref: '#/components/schemas/checkout_rates_option_request_body'
          description: The delivery options to create with the configuration.
        shared_settings:
          allOf:
            - $ref: '#/components/schemas/checkout_rates_shared_settings'
          description: Settings shared by every option in the configuration.
    checkout_rates_config_response_body:
      title: checkout_rates_config_response_body
      type: object
      description: >-
        A checkout rates configuration with its delivery options and shared
        settings.
      additionalProperties: false
      properties:
        config_id:
          type: string
          readOnly: true
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          description: The unique identifier of the configuration.
        options:
          type: array
          items:
            $ref: '#/components/schemas/checkout_rates_option_response_body'
          description: The delivery options in the configuration.
        shared_settings:
          allOf:
            - $ref: '#/components/schemas/checkout_rates_shared_settings'
          description: Settings shared by every option in the configuration.
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2026-05-15T18:30:00Z'
          description: When the configuration was created.
    checkout_rates_config_summary:
      title: checkout_rates_config_summary
      type: object
      description: >-
        An identifying summary of a checkout rates configuration, as returned
        when listing configurations.
      additionalProperties: false
      properties:
        config_id:
          type: string
          readOnly: true
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          description: The unique identifier of the configuration.
        is_active:
          type: boolean
          readOnly: true
          example: true
          description: Whether the configuration is active.
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2026-05-15T18:30:00Z'
          description: When the configuration was created.
    list_checkout_rates_configs_response_body:
      title: list_checkout_rates_configs_response_body
      type: array
      description: The checkout rates configurations on the account.
      items:
        $ref: '#/components/schemas/checkout_rates_config_summary'
    checkout_rates_ship_to:
      title: checkout_rates_ship_to
      type: object
      description: The destination address to calculate rates for.
      additionalProperties: false
      properties:
        address_type:
          type: string
          example: residential
          description: >-
            The kind of address, when known (for example, `residential` or
            `commercial`).
        address_line1:
          type: string
          example: 525 S Winchester Blvd
          description: The first line of the street address.
        address_line2:
          type: string
          example: Suite 200
          description: The second line of the street address, when applicable.
        city_locality:
          type: string
          example: San Jose
          description: The city or locality.
        state_province:
          type: string
          example: CA
          description: The state or province.
        postal_code:
          type: string
          example: '95128'
          description: The postal code.
        country_code:
          type: string
          example: US
          description: The ISO 3166-1 alpha-2 country code.
    checkout_rates_item:
      title: checkout_rates_item
      type: object
      description: A line item in the cart being rated.
      additionalProperties: false
      properties:
        name:
          type: string
          example: T-Shirt
          description: The name of the item.
        quantity:
          type: integer
          example: 2
          description: The number of units of the item in the cart.
        sku:
          type: string
          example: SKU-1234
          description: The stock keeping unit (SKU) of the item.
        price:
          type: number
          example: 19.99
          description: The unit price of the item.
        weight:
          allOf:
            - $ref: '#/components/schemas/weight'
          description: The weight of a single unit of the item.
        dimensions:
          allOf:
            - $ref: '#/components/schemas/dimensions'
          description: The dimensions of a single unit of the item.
    calculate_checkout_rates_request_body:
      title: calculate_checkout_rates_request_body
      type: object
      description: The destination and cart contents to calculate checkout rates for.
      additionalProperties: false
      required:
        - ship_to
        - items
      properties:
        ship_to:
          allOf:
            - $ref: '#/components/schemas/checkout_rates_ship_to'
          description: The destination address.
        items:
          type: array
          items:
            $ref: '#/components/schemas/checkout_rates_item'
          description: The items in the cart.
        currency:
          type: string
          example: USD
          description: The currency to return rates in.
    checkout_rates_rate_option:
      title: checkout_rates_rate_option
      type: object
      description: >-
        A single rate returned for a delivery option. Each rate is an
        individually retrievable quote identified by its own `quote_id`.
      additionalProperties: false
      properties:
        quote_id:
          type: string
          readOnly: true
          example: f1a2b3c4-d5e6-7890-abcd-ef1234567890
          description: >-
            The unique identifier of this rate's quote. Use it to retrieve the
            quote later with [Get a checkout rate
            quote](#operation/get_checkout_rates_quote).
        option_id:
          type: integer
          readOnly: true
          example: 100001
          description: The identifier of the delivery option this rate was produced for.
        option_name:
          type: string
          readOnly: true
          example: Standard Shipping
          description: The display name of the delivery option.
        type:
          type: string
          readOnly: true
          enum:
            - live_rate
            - flat_rate
            - free
            - local_delivery
          example: live_rate
          description: >-
            The delivery option type this rate corresponds to (for example,
            `live_rate` or `free`).
        carrier_id:
          type: string
          nullable: true
          readOnly: true
          example: se-1234567
          description: >-
            The carrier this rate is for. `null` for options without a carrier
            (for example, `free`).
        service_code:
          type: string
          nullable: true
          readOnly: true
          example: usps_priority_mail
          description: >-
            The carrier service this rate is for. `null` for options without a
            carrier service.
        final_amount:
          type: number
          readOnly: true
          example: 10.69
          description: The price shown to the buyer after fees or fallbacks are applied.
        currency:
          type: string
          readOnly: true
          example: USD
          description: The currency of `final_amount`.
        estimated_delivery_days:
          type: integer
          nullable: true
          readOnly: true
          example: 2
          description: The estimated number of days in transit, when available.
        estimated_delivery_date:
          type: string
          format: date-time
          nullable: true
          readOnly: true
          example: '2026-06-26T00:00:00Z'
          description: The estimated delivery date, when available.
    calculate_checkout_rates_response_body:
      title: calculate_checkout_rates_response_body
      type: object
      description: The rates calculated for a cart. Each rate carries its own `quote_id`.
      additionalProperties: false
      properties:
        config_id:
          type: string
          readOnly: true
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          description: The configuration the rates were calculated against.
        rates:
          type: array
          items:
            $ref: '#/components/schemas/checkout_rates_rate_option'
          description: >-
            The rates to display at checkout, one entry per delivery option that
            produced a rate. Each entry has its own `quote_id`.
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2026-06-24T10:00:00Z'
          description: When the quote was calculated.
    checkout_rates_quote_response_body:
      title: checkout_rates_quote_response_body
      type: object
      description: A previously calculated rate quote.
      additionalProperties: false
      properties:
        config_id:
          type: string
          readOnly: true
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          description: The configuration the rate was calculated against.
        quote:
          allOf:
            - $ref: '#/components/schemas/checkout_rates_rate_option'
          description: The rate returned for this quote, including its `quote_id`.
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2026-06-24T10:00:00Z'
          description: When the quote was calculated.
    freight_address:
      title: freight_address
      type: object
      description: >
        An origin or destination address for a freight shipment. LTL carriers
        require a contact name, company name, and phone number at both ends of
        the shipment so the driver can arrange pickup and delivery.
      additionalProperties: false
      required:
        - name
        - company_name
        - address_line1
        - city_locality
        - state_province
        - postal_code
        - country_code
        - phone
      properties:
        name:
          type: string
          example: Marcus Bell
          description: The name of the contact person at this location.
        company_name:
          type: string
          example: Northgate Distribution
          description: The name of the business at this location.
        address_line1:
          type: string
          example: 4200 Industrial Pkwy
          description: The first line of the street address.
        address_line2:
          type: string
          nullable: true
          example: Dock 12
          description: >-
            The second line of the street address, such as a dock or suite
            number.
        city_locality:
          type: string
          example: Grand Rapids
          description: The city or locality.
        state_province:
          type: string
          example: MI
          description: The state or province.
        postal_code:
          type: string
          example: '49512'
          description: The postal code.
        country_code:
          type: string
          example: US
          description: The two-letter ISO 3166-1 alpha-2 country code.
        phone:
          type: string
          example: +1 616 555 0142
          description: >-
            The phone number of the contact person. Carriers call this number to
            arrange pickup or delivery.
        email:
          type: string
          nullable: true
          example: dock@northgate-dist.example
          description: The email address of the contact person.
        location_type:
          type: string
          nullable: true
          enum:
            - airport
            - carrier_terminal
            - commercial
            - construction
            - container_freight_station
            - distribution_center
            - government_facility
            - limited_access
            - pier_port_wharf
            - residential
            - secured_access
            - trade_show
            - null
          example: commercial
          description: >
            How the carrier should classify this location. Location type affects
            accessorial charges — for example, residential and limited-access
            locations usually carry a surcharge. An unrecognized value is
            rejected with a `400 Bad Request`.
    freight_tradeshow:
      title: freight_tradeshow
      type: object
      description: Identifies a tradeshow when picking up from or delivering to one.
      additionalProperties: false
      properties:
        name:
          type: string
          example: Midwest Home & Garden Expo
          description: The name of the tradeshow.
        booth_number:
          type: string
          example: B-1147
          description: The booth number at the tradeshow.
    freight_accessorials:
      title: freight_accessorials
      type: object
      description: >
        Additional services requested from the carrier. Accessorials affect the
        price of every quote, so request them when you quote — there is no
        `accessorials` field on the booking request. The offer you book already
        carries the accessorials it was priced with, so adding one afterwards
        requires requesting fresh quotes.
      additionalProperties: false
      properties:
        liftgate_pickup:
          type: boolean
          default: false
          example: true
          description: >-
            The origin has no loading dock and the driver needs a liftgate to
            load the freight.
        inside_pickup:
          type: boolean
          default: false
          example: false
          description: >-
            The driver needs to collect the freight from inside the building
            rather than at the dock or curb.
        carrier_terminal_pickup:
          type: boolean
          default: false
          example: false
          description: >-
            The freight is dropped off at the carrier's terminal instead of
            being collected.
        grocery_consolidation_pickup:
          type: boolean
          default: false
          example: false
          description: The origin is a grocery consolidation facility.
        liftgate_delivery:
          type: boolean
          default: false
          example: true
          description: >-
            The destination has no loading dock and the driver needs a liftgate
            to unload the freight.
        inside_delivery:
          type: boolean
          default: false
          example: false
          description: >-
            The driver needs to bring the freight inside the building rather
            than leave it at the dock or curb.
        appointment_delivery:
          type: boolean
          default: false
          example: false
          description: The carrier must schedule a delivery appointment with the consignee.
        notify_before_delivery:
          type: boolean
          default: false
          example: true
          description: The carrier must call the consignee before delivering.
        hold_at_terminal:
          type: boolean
          default: false
          example: false
          description: >-
            The carrier holds the freight at the destination terminal for the
            consignee to collect.
        grocery_consolidation_delivery:
          type: boolean
          default: false
          example: false
          description: The destination is a grocery consolidation facility.
        sort_and_segregate:
          type: boolean
          default: false
          example: false
          description: The carrier sorts or segregates the freight on delivery.
        protection_from_cold:
          type: boolean
          default: false
          example: false
          description: The freight must be protected from freezing.
        protection_from_heat:
          type: boolean
          default: false
          example: false
          description: The freight must be protected from heat.
        tradeshow_pickup:
          allOf:
            - $ref: '#/components/schemas/freight_tradeshow'
          description: >-
            The freight is collected from a tradeshow. Providing this object
            requests the tradeshow pickup accessorial.
        tradeshow_delivery:
          allOf:
            - $ref: '#/components/schemas/freight_tradeshow'
          description: >-
            The freight is delivered to a tradeshow. Providing this object
            requests the tradeshow delivery accessorial.
    freight_insurance:
      title: freight_insurance
      type: object
      description: >
        Requests cargo insurance for the shipment. When present, quotes include
        the insurance premium and, once bound, a certificate number. Insured
        values are always in USD.
      additionalProperties: false
      required:
        - insured_value
      properties:
        insured_value:
          type: number
          format: double
          example: 18500
          description: >
            The declared value of the freight to insure, in USD. Always send
            this: it is not currently validated, so omitting it requests
            insurance with a declared value of `0` rather than returning an
            error.
        item_condition:
          type: string
          nullable: true
          enum:
            - new
            - used
            - null
          default: new
          example: new
          description: >
            The condition of the insured goods. Maximum liability differs
            between new and used freight. Unrecognized values are ignored rather
            than rejected.
        commodity_category:
          type: string
          nullable: true
          enum:
            - general_merchandise
            - equipment
            - food_and_beverages
            - chemicals
            - electronics
            - construction_materials
            - furniture
            - stonework
            - fragile
            - perishables
            - jewelry
            - motorized_transportation
            - art_and_antiques
            - explosives
            - life_forms
            - controlled_items
            - pharmaceuticals_non_refrigerated
            - pharmaceuticals_refrigerated
            - null
          default: general_merchandise
          example: furniture
          description: >
            The category of the insured goods. Some categories are excluded or
            restricted by the insurer. Unrecognized values fall back to
            `general_merchandise` rather than returning an error.
        marks_numbers:
          type: string
          nullable: true
          example: NG-2026-0417
          description: >-
            The marks and numbers identifying the insured freight on the
            shipping documents.
    freight_hazardous_materials:
      title: freight_hazardous_materials
      type: object
      description: >
        Hazardous materials (hazmat) details for a commodity. Providing this
        object flags the commodity as hazmat, which the carrier prints on the
        Bill of Lading. All fields other than `subsidiary_hazard_classes`,
        `emergency_response_reference`, `flashpoint_temperature`, and
        `additional_details` are required.
      additionalProperties: false
      required:
        - identification_number_type
        - identification_number
        - proper_shipping_name
        - hazard_class
        - packing_group
        - emergency_contact_name
        - emergency_contact_phone
      properties:
        identification_number_type:
          type: string
          enum:
            - un
            - na
          example: un
          description: >
            The authority that issued the identification number: `un` for a
            United Nations number or `na` for a North America number.
        identification_number:
          type: string
          maxLength: 50
          example: UN1263
          description: The UN or NA number identifying the hazardous material.
        proper_shipping_name:
          type: string
          maxLength: 200
          example: Paint
          description: >-
            The proper shipping name of the hazardous material, as published in
            the hazardous materials table.
        hazard_class:
          type: string
          enum:
            - 1.1A
            - 1.1B
            - 1.1C
            - 1.1D
            - 1.1E
            - 1.1F
            - 1.1G
            - 1.1J
            - 1.1L
            - 1.2B
            - 1.2C
            - 1.2D
            - 1.2E
            - 1.2F
            - 1.2G
            - 1.2H
            - 1.2J
            - 1.2K
            - 1.2L
            - 1.3C
            - 1.3G
            - 1.3H
            - 1.3J
            - 1.3K
            - 1.3L
            - 1.4B
            - 1.4C
            - 1.4D
            - 1.4E
            - 1.4F
            - 1.4G
            - 1.4S
            - 1.5D
            - 1.6N
            - '2.1'
            - '2.2'
            - '2.3'
            - '3'
            - '4.1'
            - '4.2'
            - '4.3'
            - '5.1'
            - '5.2'
            - '6.1'
            - '6.2'
            - '7'
            - '8'
            - '9'
          example: '3'
          description: The primary hazard class or division of the material.
        subsidiary_hazard_classes:
          type: array
          items:
            type: string
            example: '8'
          example:
            - '8'
          description: >
            Any subsidiary hazard classes, using the same values as
            `hazard_class`. Values must be unique and must not repeat the
            primary `hazard_class`.
        packing_group:
          type: string
          enum:
            - i
            - ii
            - iii
            - none
          example: iii
          description: >-
            The packing group assigned to the material, or `none` when the
            material has no packing group.
        emergency_contact_name:
          type: string
          maxLength: 200
          example: Chemtrec
          description: The name of the 24-hour emergency response contact.
        emergency_contact_phone:
          type: string
          maxLength: 50
          example: +1 800 424 9300
          description: The phone number of the 24-hour emergency response contact.
        emergency_response_reference:
          type: string
          nullable: true
          maxLength: 10
          example: CCN12345
          description: >-
            The emergency response registration or contract number, such as a
            CHEMTREC contract number.
        flashpoint_temperature:
          type: number
          nullable: true
          format: double
          example: 73
          description: >-
            The flashpoint of the material in degrees Fahrenheit, when it has
            one.
        additional_details:
          type: string
          nullable: true
          maxLength: 250
          example: Keep upright. Do not stack.
          description: >-
            Any additional hazmat information the carrier should print on the
            Bill of Lading.
    freight_commodity:
      title: freight_commodity
      type: object
      description: >
        A line of goods inside a handling unit. Every handling unit needs at
        least one commodity, and each commodity carries its own freight class.
      additionalProperties: false
      required:
        - quantity
        - weight
        - weight_unit
        - freight_class
      properties:
        description:
          type: string
          nullable: true
          example: Assembled oak dining chairs
          description: >-
            A description of the goods. Carriers print this on the Bill of
            Lading.
        quantity:
          type: integer
          format: int32
          minimum: 1
          example: 24
          description: >-
            The number of pieces of this commodity inside a single handling
            unit.
        weight:
          type: number
          format: double
          minimum: 0
          exclusiveMinimum: true
          example: 310
          description: >-
            The total weight of this commodity line inside a single handling
            unit.
        weight_unit:
          allOf:
            - $ref: '#/components/schemas/weight_unit'
          description: The unit of measure for `weight`.
        value:
          type: number
          nullable: true
          format: double
          deprecated: true
          example: 4800
          description: >
            Accepted but ignored. This field is not sent to the carrier and is
            not stored. To declare a value for cargo insurance, use
            `insurance.insured_value` on the quote request instead.
        packaging_type:
          type: string
          nullable: true
          enum:
            - bag
            - bale
            - box
            - bundle
            - carton
            - case
            - crate
            - cylinder
            - drum
            - pail
            - pallet
            - pieces
            - reel
            - roll
            - skid
            - tank
            - tote
            - trailer
            - tube
            - null
          example: carton
          description: >
            How this commodity is packaged inside the handling unit.
            Unrecognized values are ignored rather than rejected.
        freight_class:
          type: string
          enum:
            - '50'
            - '55'
            - '60'
            - '65'
            - '70'
            - '77.5'
            - '85'
            - '92.5'
            - '100'
            - '110'
            - '125'
            - '150'
            - '175'
            - '200'
            - '250'
            - '300'
            - '400'
            - '500'
          example: '125'
          description: >
            The National Motor Freight Traffic Association (NMFTA) [freight
            class](https://nmfta.org/nmfc/) of the goods. Freight class is
            derived from density, stowability, handling, and liability, and is
            one of the largest factors in the price of an LTL shipment.
        nmfc_code:
          type: string
          nullable: true
          example: 80700-2
          description: The NMFC item and sub number for the goods.
        hazardous_materials:
          allOf:
            - $ref: '#/components/schemas/freight_hazardous_materials'
          description: Hazmat details. Provide this object only for hazardous commodities.
    freight_handling_unit:
      title: freight_handling_unit
      type: object
      description: >
        A physical unit the carrier handles, such as a pallet or crate, together
        with the goods it contains.
      additionalProperties: false
      required:
        - quantity
        - length
        - width
        - height
        - dimension_unit
        - commodities
      properties:
        type:
          type: string
          nullable: true
          enum:
            - bag
            - bale
            - box
            - bundle
            - carton
            - case
            - crate
            - cylinder
            - drum
            - pail
            - pallet
            - pieces
            - reel
            - roll
            - skid
            - tank
            - tote
            - trailer
            - tube
            - null
          default: pallet
          example: pallet
          description: >
            The kind of handling unit. Defaults to `pallet`. Unrecognized values
            are ignored rather than rejected.
        quantity:
          type: integer
          format: int32
          minimum: 1
          example: 2
          description: >
            The number of identical handling units being shipped. The
            dimensions, weight, and commodities describe one of them; the
            carrier multiplies them out.
        length:
          type: number
          format: double
          minimum: 0
          exclusiveMinimum: true
          example: 48
          description: >-
            The length of a single handling unit, in the unit specified by
            `dimension_unit`.
        width:
          type: number
          format: double
          minimum: 0
          exclusiveMinimum: true
          example: 40
          description: >-
            The width of a single handling unit, in the unit specified by
            `dimension_unit`.
        height:
          type: number
          format: double
          minimum: 0
          exclusiveMinimum: true
          example: 52
          description: >-
            The height of a single handling unit, in the unit specified by
            `dimension_unit`.
        dimension_unit:
          allOf:
            - $ref: '#/components/schemas/dimension_unit'
          description: The unit of measure for `length`, `width`, and `height`.
        stackable:
          type: boolean
          default: false
          example: false
          description: >
            Whether the carrier may stack other freight on top of this handling
            unit. Non-stackable freight consumes more trailer space and can cost
            more.
        commodities:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/freight_commodity'
          description: >-
            The goods inside a single handling unit. At least one commodity is
            required.
    freight_pickup_details:
      title: freight_pickup_details
      type: object
      description: >
        When the carrier can collect the freight. The ready and close times
        define the pickup window at the origin, and the carrier needs a window
        wide enough for a driver to arrive.
      additionalProperties: false
      required:
        - pickup_date
        - ready_time
        - close_time
      properties:
        pickup_date:
          type: string
          format: date-time
          example: '2026-04-17T00:00:00Z'
          description: The date the freight is ready to be collected.
        ready_time:
          type: string
          pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
          example: '09:00'
          description: >-
            The earliest time the freight can be collected, in 24-hour `HH:mm`
            format and local to the origin.
        close_time:
          type: string
          pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
          example: '16:30'
          description: >-
            The time the origin closes, in 24-hour `HH:mm` format and local to
            the origin.
        is_self_scheduled:
          type: boolean
          default: false
          example: false
          description: >
            Whether you arrange the pickup with the carrier yourself. When
            `true`, ShipEngine does not request a pickup on your behalf.
        location_type:
          type: string
          nullable: true
          enum:
            - airport
            - carrier_terminal
            - commercial
            - construction
            - container_freight_station
            - distribution_center
            - government_facility
            - limited_access
            - pier_port_wharf
            - residential
            - secured_access
            - trade_show
            - null
          example: commercial
          description: >
            How the carrier should classify the pickup location. An unrecognized
            value is rejected with a `400 Bad Request`.
    freight_reference:
      title: freight_reference
      type: object
      description: >
        A reference number the carrier prints on the Bill of Lading, such as a
        purchase order or sales order number.
      additionalProperties: false
      properties:
        type:
          type: string
          nullable: true
          example: purchase_order
          description: >
            A free-form label for the reference, such as `purchase_order`,
            `sales_order`, or `reference_1`. The values a carrier can print vary
            by carrier.
        value:
          type: string
          nullable: true
          example: PO-84213
          description: >
            The reference value. Not length-validated by the API, but keep it
            short — carriers commonly truncate reference values to around 35
            characters on the Bill of Lading.
    freight_provider_account:
      title: freight_provider_account
      type: object
      description: |
        A freight provider account connected to your account.
      additionalProperties: false
      properties:
        freight_provider_account_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The identifier of the freight provider account. Pass it as
            `freight_provider_account_id` when quoting, booking, or tracking.
        freight_provider_code:
          type: string
          readOnly: true
          example: UNISHIPPERS
          description: >
            The code of the freight provider, such as `UNISHIPPERS` or `WWEX`.
            This is the same value returned as `freight_provider_code` on
            quotes, shipments, and tracking.
        nickname:
          type: string
          nullable: true
          readOnly: true
          example: Unishippers - Midwest
          description: >-
            The name given to the connection when it was set up, or `null` when
            it has none.
    list_freight_provider_accounts_response_body:
      title: list_freight_provider_accounts_response_body
      type: object
      description: The freight provider accounts connected to your account.
      additionalProperties: false
      properties:
        freight_provider_accounts:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/freight_provider_account'
          description: >
            The active freight provider accounts on the account. An empty array
            when no freight provider is connected.
    get_freight_quotes_request_body:
      title: get_freight_quotes_request_body
      type: object
      description: >
        A freight quote request. Either describe the shipment inline with
        `ship_from`, `ship_to`, and `handling_units`, or link it to an existing
        shipment with `shipment_id`.
      additionalProperties: false
      required:
        - freight_provider_account_id
      properties:
        freight_provider_account_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The freight provider account to quote against. It must be an active
            connection on your account — retrieve it with [List freight provider
            accounts](#operation/list_freight_provider_accounts).
        shipment_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            An existing shipment to quote for. When provided, the origin is
            taken from the shipment's ship-from warehouse and the destination
            from the order's ship-to address, and `ship_from` and `ship_to` must
            be omitted. The `handling_units`, `accessorials`, and `insurance`
            you send are saved as the shipment's freight configuration; omit
            them to reuse the configuration already saved.
        ship_from:
          allOf:
            - $ref: '#/components/schemas/freight_address'
          description: >
            The origin address. Required when `shipment_id` is omitted, and must
            not be provided when `shipment_id` is present.
        ship_to:
          allOf:
            - $ref: '#/components/schemas/freight_address'
          description: >
            The destination address. Required when `shipment_id` is omitted, and
            must not be provided when `shipment_id` is present.
        shipment_date:
          type: string
          nullable: true
          format: date-time
          example: '2026-04-17T00:00:00Z'
          description: >-
            The date the freight is ready to ship. Defaults to the current date
            when omitted.
        handling_units:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/freight_handling_unit'
          description: >
            The handling units being shipped. Required when `shipment_id` is
            omitted.
        accessorials:
          allOf:
            - $ref: '#/components/schemas/freight_accessorials'
          description: Additional services to include in the quote.
        insurance:
          allOf:
            - $ref: '#/components/schemas/freight_insurance'
          description: Cargo insurance to quote alongside the freight charges.
    freight_quote:
      title: freight_quote
      type: object
      description: |
        A bookable freight offer from a single LTL carrier.
      additionalProperties: false
      properties:
        freight_provider_account_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The freight provider account that returned the offer.
        freight_provider_code:
          type: string
          readOnly: true
          example: UNISHIPPERS
          description: The code of the freight provider that returned the offer.
        offer_id:
          type: string
          nullable: true
          readOnly: true
          example: 0f2b41d8-6a17-4c9e-8f52-b71d3e9c4a68
          description: >
            Identifies this offer when booking. Resolves server-side to the
            provider connection, carrier, and expiration — pass this id alone to
            [Book a freight shipment](#operation/book_freight_shipment).
        carrier_name:
          type: string
          nullable: true
          readOnly: true
          example: FedEx Freight Economy
          description: The name of the LTL carrier that would move the freight.
        carrier_scac:
          type: string
          nullable: true
          readOnly: true
          example: FXFE
          description: The Standard Carrier Alpha Code (SCAC) of the LTL carrier.
        service_name:
          type: string
          nullable: true
          readOnly: true
          example: Standard LTL
          description: The name of the service level the carrier is offering.
        service_type:
          type: string
          nullable: true
          readOnly: true
          example: Direct
          description: >
            Whether the origin terminal serves the lane directly (`Direct`) or
            hands the freight to another carrier (`Interline`).
        total_charges:
          type: number
          format: double
          readOnly: true
          example: 842.37
          description: >-
            The total price of the offer in USD, including any accessorials and
            insurance premium.
        transit_days:
          type: integer
          format: int32
          readOnly: true
          example: 3
          description: The carrier's estimated number of transit days.
        estimated_delivery_date:
          type: string
          nullable: true
          format: date-time
          readOnly: true
          example: '2026-04-22T00:00:00Z'
          description: The carrier's estimated delivery date, when provided.
        is_guaranteed:
          type: boolean
          readOnly: true
          example: false
          description: Whether the carrier guarantees the transit time for this offer.
        origin_terminal_code:
          type: string
          nullable: true
          readOnly: true
          example: GRR
          description: The code of the carrier terminal serving the origin.
        destination_terminal_code:
          type: string
          nullable: true
          readOnly: true
          example: DFW
          description: The code of the carrier terminal serving the destination.
        insured_amount:
          type: number
          nullable: true
          format: double
          readOnly: true
          example: 18500
          description: The insured value in USD, when insurance was requested.
        insurance_premium:
          type: number
          nullable: true
          format: double
          readOnly: true
          example: 46.25
          description: >-
            The insurance premium in USD included in `total_charges`, when
            insurance was requested.
        insurance_certificate_number:
          type: string
          nullable: true
          readOnly: true
          example: CRT-4471902
          description: >
            The insurance certificate number, when the insurer issued one for
            the offer. `null` when no insurance was requested.
        quote_expiration_date:
          type: string
          nullable: true
          format: date-time
          readOnly: true
          example: '2026-04-16T23:59:59Z'
          description: When the offer expires. Expiry is enforced server-side when booking.
        max_liability_new:
          type: number
          nullable: true
          format: double
          readOnly: true
          example: 25
          description: >
            The carrier's maximum liability per pound for new goods, in USD.
            Carrier liability is far below the value of most freight, which is
            why cargo insurance is usually worth quoting.
        max_liability_used:
          type: number
          nullable: true
          format: double
          readOnly: true
          example: 10
          description: The carrier's maximum liability per pound for used goods, in USD.
    freight_quotes_response_body:
      title: freight_quotes_response_body
      type: object
      description: The freight offers returned for a quote request.
      additionalProperties: false
      properties:
        quotes:
          type: array
          nullable: true
          readOnly: true
          items:
            $ref: '#/components/schemas/freight_quote'
          description: >
            The offers returned by the provider, one per carrier and service
            combination. When no carrier can serve the lane as described, this
            is an empty array or `null`.
    book_freight_shipment_request_body:
      title: book_freight_shipment_request_body
      type: object
      description: >
        A request to book a freight offer returned by a quote. Pass the
        `offer_id` from the offer being booked — the provider connection,
        carrier, and expiration are resolved server-side.
      additionalProperties: false
      required:
        - offer_id
        - pickup_details
      properties:
        shipment_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The shipment the offer was quoted for. When provided, the shipment
            must already have a freight quote, and `ship_from`, `ship_to`, and
            `handling_units` must be omitted — the origin, destination, and
            handling units all come from the shipment and its saved freight
            configuration.
        offer_id:
          type: string
          minLength: 1
          example: 0f2b41d8-6a17-4c9e-8f52-b71d3e9c4a68
          description: >
            The `offer_id` of the quoted offer being booked. Resolves
            server-side to the provider connection, the carrier, and the
            expiration.
        ship_from:
          allOf:
            - $ref: '#/components/schemas/freight_address'
          description: >
            The origin address. Required when `shipment_id` is omitted, and must
            not be provided when `shipment_id` is present.
        ship_to:
          allOf:
            - $ref: '#/components/schemas/freight_address'
          description: >
            The destination address. Required when `shipment_id` is omitted, and
            must not be provided when `shipment_id` is present.
        handling_units:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/freight_handling_unit'
          description: >
            The handling units being shipped. Required when `shipment_id` is
            omitted, and must not be provided when `shipment_id` is present.
        pickup_details:
          allOf:
            - $ref: '#/components/schemas/freight_pickup_details'
          description: When the carrier can collect the freight. Always required.
        references:
          type: array
          items:
            $ref: '#/components/schemas/freight_reference'
          description: Reference numbers for the carrier to print on the Bill of Lading.
        pickup_instructions:
          type: string
          nullable: true
          example: Check in with the guard at gate 3 before backing into dock 12.
          description: Instructions for the driver at the origin.
        delivery_instructions:
          type: string
          nullable: true
          example: Delivery appointments accepted between 08:00 and 11:00 only.
          description: Instructions for the driver at the destination.
        handling_instructions:
          type: string
          nullable: true
          example: Do not double stack. Load with forks from the long side.
          description: Instructions for handling the freight in transit.
    freight_shipment_status:
      title: freight_shipment_status
      type: string
      readOnly: true
      enum:
        - pending
        - quoted
        - booked
        - in_transit
        - delivered
        - cancelled
        - exception
      example: booked
      description: >
        The lifecycle status of a freight shipment. `exception` is also returned
        when the status cannot be determined.
    freight_booked_document:
      title: freight_booked_document
      type: object
      description: >
        A document the carrier generated when the shipment was booked. Each
        entry includes a `type` and a `url` you can use to download it directly.
      additionalProperties: false
      properties:
        type:
          type: string
          readOnly: true
          example: BILL_OF_LADING
          description: >
            The type of document, as reported by the freight provider — for
            example `BILL_OF_LADING`, `PALLET_LABEL`, or
            `BOL_PALLET_LABEL_COMBINED`. Unlike the lowercase values returned by
            [List freight shipment
            documents](#operation/list_freight_shipment_documents), this is the
            provider's raw value.
        url:
          type: string
          nullable: true
          readOnly: true
          example: >-
            https://api.shipengine.com/v2/downloads/p1/a1b2c3d4e5f6/bill_of_lading.pdf
          description: |
            The path to download the document as a PDF.
    freight_shipment_document:
      title: freight_shipment_document
      type: object
      description: A document stored for a freight shipment.
      additionalProperties: false
      properties:
        type:
          type: string
          readOnly: true
          enum:
            - bill_of_lading
            - bol_pallet_label_combined
            - certificate_of_insurance
            - certificate_of_insurance_instructions
            - certificate_of_origin_us
            - certificate_of_origin_usmca
            - certificate_of_origin_usmca_instructions
            - international_commercial_invoice
            - packing_list
            - pallet_label
            - pallet_label_4x6
            - proof_of_delivery
            - quote
            - weight_and_inspection
          example: bill_of_lading
          description: The type of document.
        url:
          type: string
          nullable: true
          readOnly: true
          example: /v1/downloads/10/a1b2c3d4e5f6/bill_of_lading.pdf
          description: >
            The path to download the document as a PDF, relative to the API
            host. Resolve it against `https://api.shipengine.com` to get the
            full URL.
    book_freight_shipment_response_body:
      title: book_freight_shipment_response_body
      type: object
      description: The freight shipment created by a booking.
      additionalProperties: false
      properties:
        freight_shipment_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >-
            The identifier of the freight shipment. Use it to retrieve, track,
            or cancel the shipment.
        freight_provider_account_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The freight provider account the shipment was booked through.
        freight_provider_code:
          type: string
          readOnly: true
          example: UNISHIPPERS
          description: The code of the freight provider the shipment was booked through.
        status:
          allOf:
            - $ref: '#/components/schemas/freight_shipment_status'
          description: The status of the shipment. A successful booking returns `booked`.
        bol_number:
          type: string
          nullable: true
          readOnly: true
          example: BOL-20260417-4821
          description: The Bill of Lading number assigned to the shipment.
        pro_number:
          type: string
          nullable: true
          readOnly: true
          example: 072-51293847
          description: >
            The carrier's PRO number for the shipment. Carriers often assign
            this after pickup, so it is usually `null` immediately after
            booking.
        confirmation_number:
          type: string
          nullable: true
          readOnly: true
          example: FXFE-PU-884215
          description: >
            The carrier's pickup confirmation number. `null` when the carrier
            did not return one.
        documents:
          type: array
          nullable: true
          readOnly: true
          items:
            $ref: '#/components/schemas/freight_booked_document'
          description: >
            The documents the carrier generated for the booking. `null` when the
            provider reported none.
    freight_shipment_response_body:
      title: freight_shipment_response_body
      type: object
      description: A freight shipment on your account.
      additionalProperties: false
      properties:
        freight_shipment_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The identifier of the freight shipment.
        freight_provider_account_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The freight provider account the shipment was booked through.
        freight_provider_code:
          type: string
          readOnly: true
          example: UNISHIPPERS
          description: The code of the freight provider the shipment was booked through.
        status:
          allOf:
            - $ref: '#/components/schemas/freight_shipment_status'
          description: The current status of the shipment.
        bol_number:
          type: string
          nullable: true
          readOnly: true
          example: BOL-20260417-4821
          description: The Bill of Lading number assigned to the shipment.
        pro_number:
          type: string
          nullable: true
          readOnly: true
          example: 072-51293847
          description: >-
            The carrier's PRO number for the shipment, or `null` until the
            carrier assigns one.
        confirmation_number:
          type: string
          nullable: true
          readOnly: true
          example: FXFE-PU-884215
          description: >
            The carrier's pickup confirmation number. `null` when the carrier
            did not return one.
        documents:
          type: array
          nullable: true
          readOnly: true
          items:
            $ref: '#/components/schemas/freight_shipment_document'
          description: >
            The documents stored for the shipment, each with a download URL.
            `null` when no documents have been stored yet.
    list_freight_shipments_response_body:
      title: list_freight_shipments_response_body
      type: object
      description: A page of freight shipments.
      additionalProperties: false
      properties:
        shipments:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/freight_shipment_response_body'
          description: The freight shipments on this page.
        total:
          type: integer
          format: int32
          readOnly: true
          example: 137
          description: The total number of freight shipments on the account.
        page:
          type: integer
          format: int32
          readOnly: true
          example: 1
          description: The page of results returned.
        page_size:
          type: integer
          format: int32
          readOnly: true
          example: 25
          description: The number of freight shipments per page.
        pages:
          type: integer
          format: int32
          readOnly: true
          example: 6
          description: The total number of pages available.
    cancel_freight_shipment_response_body:
      title: cancel_freight_shipment_response_body
      type: object
      description: The result of cancelling a freight shipment.
      additionalProperties: false
      properties:
        freight_shipment_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The freight shipment that was cancelled.
        pickup_cancelled:
          type: boolean
          readOnly: true
          example: true
          description: >
            `true` when the carrier also voided the associated pickup request.
            `false` when the shipment had no pickup or the carrier did not
            confirm the pickup was cancelled.
    freight_document:
      title: freight_document
      type: object
      description: A downloadable document for a freight shipment.
      additionalProperties: false
      properties:
        type:
          type: string
          readOnly: true
          enum:
            - bill_of_lading
            - bol_pallet_label_combined
            - certificate_of_insurance
            - certificate_of_insurance_instructions
            - certificate_of_origin_us
            - certificate_of_origin_usmca
            - certificate_of_origin_usmca_instructions
            - international_commercial_invoice
            - packing_list
            - pallet_label
            - pallet_label_4x6
            - proof_of_delivery
            - quote
            - weight_and_inspection
          example: bill_of_lading
          description: The type of document.
        created_at:
          type: string
          nullable: true
          format: date-time
          readOnly: true
          example: '2026-04-16T14:32:07Z'
          description: When the document was created.
        url:
          type: string
          nullable: true
          readOnly: true
          example: /v1/downloads/10/a1b2c3d4e5f6/bill_of_lading.pdf
          description: >
            The path to download the document as a PDF, relative to the API
            host. Resolve it against `https://api.shipengine.com` to get the
            full URL.
    list_freight_shipment_documents_response_body:
      title: list_freight_shipment_documents_response_body
      type: object
      description: The documents available for a freight shipment.
      additionalProperties: false
      properties:
        documents:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/freight_document'
          description: >
            The documents available for the shipment. The list grows as the
            shipment progresses — a proof of delivery, for example, only exists
            after delivery.
    freight_tracking_event_document:
      title: freight_tracking_event_document
      type: object
      description: A document the carrier attached to a tracking event.
      additionalProperties: false
      properties:
        type:
          type: string
          nullable: true
          readOnly: true
          example: PROOF_OF_DELIVERY
          description: The type of document, as reported by the carrier.
        filename:
          type: string
          nullable: true
          readOnly: true
          example: pod_072-51293847.pdf
          description: The name of the document file.
        format:
          type: string
          nullable: true
          readOnly: true
          example: PDF
          description: The file format of the document.
    freight_tracking_event:
      title: freight_tracking_event
      type: object
      description: A single tracking event reported by the carrier.
      additionalProperties: false
      properties:
        occurred_at:
          type: string
          nullable: true
          readOnly: true
          example: '2026-04-20T14:05:00Z'
          description: >
            When the event occurred, in `YYYY-MM-DDTHH:mm:ssZ` format. Carriers
            that report only a date return midnight as the time.
        status:
          type: string
          nullable: true
          readOnly: true
          example: in_transit
          description: The tracking status the event corresponds to.
        carrier_code:
          type: string
          nullable: true
          readOnly: true
          example: AF
          description: The carrier's own status or event code.
        description:
          type: string
          nullable: true
          readOnly: true
          example: Departed terminal in Grand Rapids, MI
          description: The carrier's description of the event.
        documents:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/freight_tracking_event_document'
          description: >
            Any documents the carrier attached to the event, such as a proof of
            delivery. Always present; an empty array when the carrier attached
            none.
    freight_shipment_tracking_response_body:
      title: freight_shipment_tracking_response_body
      type: object
      description: Live carrier tracking for a booked freight shipment.
      additionalProperties: false
      properties:
        freight_shipment_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The freight shipment being tracked.
        freight_provider_account_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The freight provider account used to retrieve the tracking.
        freight_provider_code:
          type: string
          readOnly: true
          example: UNISHIPPERS
          description: The code of the freight provider used to retrieve the tracking.
        carrier_scac:
          type: string
          nullable: true
          readOnly: true
          example: FXFE
          description: The SCAC of the LTL carrier moving the freight.
        bol_number:
          type: string
          nullable: true
          readOnly: true
          example: BOL-20260417-4821
          description: The Bill of Lading number of the shipment.
        pro_number:
          type: string
          nullable: true
          readOnly: true
          example: 072-51293847
          description: >-
            The carrier's PRO number for the shipment, or `null` until the
            carrier assigns one.
        status:
          allOf:
            - $ref: '#/components/schemas/freight_shipment_status'
          description: The shipment status derived from the carrier's tracking status.
        tracking_status:
          type: string
          nullable: true
          readOnly: true
          enum:
            - unknown
            - created
            - pending_pickup
            - dispatched
            - in_route_to_pickup
            - at_pickup
            - in_transit
            - out_for_delivery
            - at_delivery
            - delivered
            - exception
            - voided
            - null
          example: in_transit
          description: >
            The detailed tracking status reported by the carrier.
            `tracking_status` is finer-grained than `status`: several tracking
            statuses, such as `dispatched` and `out_for_delivery`, all map to
            the `in_transit` shipment status.
        estimated_delivery_date:
          type: string
          nullable: true
          readOnly: true
          example: '2026-04-22'
          description: The carrier's estimated delivery date, in `YYYY-MM-DD` format.
        tracking_url:
          type: string
          nullable: true
          readOnly: true
          example: https://www.fedex.com/fedextrack/?trknbr=07251293847
          description: >-
            A carrier page where the shipment can be tracked, when the carrier
            provides one.
        last_event_at:
          type: string
          nullable: true
          readOnly: true
          example: '2026-04-20T14:05:00Z'
          description: When the most recent tracking event occurred.
        events:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/freight_tracking_event'
          description: The tracking events reported by the carrier.
    freight_tracking_response_body:
      title: freight_tracking_response_body
      type: object
      description: Live carrier tracking for a PRO or BOL number.
      additionalProperties: false
      properties:
        freight_provider_account_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: The freight provider account used to retrieve the tracking.
        freight_provider_code:
          type: string
          readOnly: true
          example: UNISHIPPERS
          description: The code of the freight provider used to retrieve the tracking.
        carrier_scac:
          type: string
          nullable: true
          readOnly: true
          example: FXFE
          description: >
            The SCAC of the LTL carrier moving the freight, as reported by the
            carrier. This echoes the provider's response, not the `carrier_scac`
            you supplied in the request, so it can be `null`.
        bol_number:
          type: string
          nullable: true
          readOnly: true
          example: BOL-20260417-4821
          description: The Bill of Lading number reported by the carrier.
        pro_number:
          type: string
          nullable: true
          readOnly: true
          example: 072-51293847
          description: The PRO number reported by the carrier.
        tracking_status:
          type: string
          nullable: true
          readOnly: true
          enum:
            - unknown
            - created
            - pending_pickup
            - dispatched
            - in_route_to_pickup
            - at_pickup
            - in_transit
            - out_for_delivery
            - at_delivery
            - delivered
            - exception
            - voided
            - null
          example: delivered
          description: The detailed tracking status reported by the carrier.
        tracking_url:
          type: string
          nullable: true
          readOnly: true
          example: https://www.fedex.com/fedextrack/?trknbr=07251293847
          description: >-
            A carrier page where the shipment can be tracked, when the carrier
            provides one.
        last_event_at:
          type: string
          nullable: true
          readOnly: true
          example: '2026-04-22T09:41:00Z'
          description: When the most recent tracking event occurred.
        events:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/freight_tracking_event'
          description: The tracking events reported by the carrier.
  responses:
    400_error_response:
      description: The request contained errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response_body'
    404_error_response:
      description: The specified resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response_body'
    500_error_response:
      description: |
        An error occurred on ShipEngine's side.

        > This error will automatically be reported to our engineers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response_body'
    409_error_response:
      description: The request conflicts with an existing resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response_body'
  securitySchemes:
    api_key:
      type: apiKey
      name: API-Key
      in: header
      description: >
        To authenticate yourself to ShipEngine, you need to include an `API-Key`
        header in each API call. If you don't include a key when making an API
        request, or if you use an incorrect or expired key, then ShipEngine will
        respond with a `401 Unauthorized` error.

        Learn more about API keys in our [authentication
        guide](https://docs.shipstation.com/apis/shipengine/docs/guides/auth).
tags:
  - name: account
    description: |
      For additional information about the ShipEngine account.
    x-displayName: Account
  - name: addresses
    description: >
      No matter your shipping volume, failed deliveries and address change
      surcharges cut into your bottom line and damage perception with customers.
      Our address validation services ensure your packages make it to the right
      place the first time. Learn how to leverage our address validation
      services here.


      ShipEngine supports address validation for virtually every country on
      Earth, including the United States, Canada, Great Britain, Australia,
      Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160
      others.
    x-displayName: Addresses
  - name: batches
    description: |
      batches
    x-displayName: Batches
  - name: carrier_accounts
    description: >
      A carrier account is a connection to a shipping carrier that allows you to
      create labels, track packages, and more.  You can connect your own carrier
      accounts to ShipEngine, or use one of our built-in carrier accounts. Learn
      more about carrier accounts here.
    x-displayName: Carrier Accounts
  - name: carriers
    description: |
      carriers
    x-displayName: Carriers
  - name: checkout_rates
    description: >
      Configure the shipping options your buyers see at checkout and calculate
      live shipping rates for a cart.


      A **checkout rates configuration** groups one or more **delivery options**
      (for example, `live_rate`, `flat_rate`, `free`, or `local_delivery`) under
      a single storefront. Once a configuration exists, call the quotes endpoint
      to return the rates a buyer should see for a given destination and cart.


      This feature translates external identifiers (`carrier_id`,
      `service_code`) to the account's connected carriers and services
      automatically.
    x-displayName: Checkout Rates
  - name: documents
    description: >
      Document Upload lets you submit self-prepared customs paperwork — such as
      Pro Forma Invoices, USMCA forms (for example, the USMCA Certification of
      Origin), and other supporting documents — directly to the carrier. Use it
      whenever a shipment requires supplemental international documentation,
      helping to prevent customs delays and delivery issues.


      Documents can be provided at either the **shipment level** or the **label
      level** — that is, before or after a label is generated:


      - **Shipment level (before a label exists).** Register the document with
      [Register a document for a
      shipment](#operation/register_shipment_document). Documents registered at
      the shipment level are forwarded to the carrier automatically.

      - **Label level (after a label is generated).** Register the document with
      [Register a document for a label](#operation/register_label_document),
      then call [Send label documents](#operation/send_label_documents) to
      transmit it to the carrier.


      To enable document upload for a shipment or label, set the
      `pending_documents` flag on the shipment's `customs` object.


      Carrier Document Upload is currently supported for **UPS** and **FedEx**
      only. Accepted document types and file size vary by carrier — see the
      [Carrier Document Upload
      guide](/apis/@shipengine/docs/labels/carrier-document-upload.md) for the
      full list.


      For **step-by-step instructions on uploading documents through the
      ShipStation API dashboard**, see the [Customs Declarations: Document
      Upload help
      article](https://help.shipstation.com/hc/en-us/articles/50888603341211).
      This is useful for operations teams who need to upload documents manually
      or as a fallback if API integration issues occur.
    x-displayName: Documents
  - name: downloads
    description: |
      downloads
    x-displayName: Downloads
  - name: freight
    description: >
      Quote, book, track, and manage less-than-truckload (LTL) freight shipments
      through a freight provider connected to your account.
    x-displayName: Freight
  - name: insurance
    description: |
      insurance
    x-displayName: Insurance
  - name: labels
    description: >
      Print shipping labels for any of the top global carriers in
      minutes—instead of weeks. Simply connect your existing carrier accounts in
      the API dashboard, and then begin creating labels.
    x-displayName: Labels
  - name: mailing
    description: >
      Create mailing labels for USPS including NetStamps, mail labels, and
      envelopes.
    x-displayName: Mailing
  - name: manifests
    description: |
      manifests
    x-displayName: Manifests
  - name: package_pickups
    description: Scheduled package pickups
    x-displayName: Package Pickups
  - name: package_types
    description: |
      custom package types
    x-displayName: Package Types
  - name: rates
    description: >
      Make sure you ship as cost-effectively as possible by quickly comparing
      rates using the ShipEngine Rates API. As long as you have the carrier
      connected to your account, you'll be able to see and compare different
      rates and services.
    x-displayName: Rates
  - name: rate_shoppers
    description: >
      Manage rate shoppers. Rate shoppers define carrier service collections and
      rules for automatic rate selection when purchasing labels. Includes both
      default strategies (cheapest, fastest, best_value) and custom
      seller-configured rate shoppers.
    x-displayName: Rate Shoppers
  - name: service_points
    description: >-
      Service points allow customers to pick up their packages at convenient
      locations.
    x-displayName: Service Points
  - name: shipments
    description: >
      Shipments are at the center of the ShipEngine API.  A shipment is the
      first step in creating a shipping label, or creating a manifest.  It's
      also essential for getting shipping rates.
    x-displayName: Shipments
  - name: tags
    description: |
      tags
    x-displayName: Tags
  - name: tokens
    description: Manage authentication tokens for secure API access.
    x-displayName: Tokens
  - name: tracking
    description: >
      Track packages across any of our 20+ supported carrier accounts and create
      tracking events to keep your customers up-to-date. Easily integrate
      real-time tracking information for shipments into your app, email, or SMS.
    x-displayName: Tracking
  - name: warehouses
    description: |
      warehouses
    x-displayName: Warehouses
  - name: webhooks
    description: >
      Webhooks are a powerful feature of ShipEngine that can save you from
      sending repeated polling requests to check on the state of something. With
      webhooks, ShipEngine will automatically contact your servers when the
      state changes. This can include parcel tracking events, notification of
      the completion of a batch operation, or new sales orders.
    x-displayName: Webhooks
security:
  - api_key: []
