openapi.yaml

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
  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.


    ## Getting Started

    If you're new to REST APIs then be sure to read our [introduction to
    REST](https://www.shipengine.com/docs/rest/) to understand the basics.
    Learn how to [authenticate yourself to
    ShipEngine](https://www.shipengine.com/docs/auth/), and then use our
    [sandbox environment](https://www.shipengine.com/docs/sandbox/) to kick the
    tires and get familiar with our API. If you run into any problems, then be
    sure to check the [error handling
    guide](https://www.shipengine.com/docs/errors/) for tips.


    Here are some step-by-step **tutorials** to get you started:

      - [Learn how to create your first shipping label](https://www.shipengine.com/docs/labels/create-a-label/)
      - [Calculate shipping costs and compare rates across carriers](https://www.shipengine.com/docs/rates/)
      - [Track packages on-demand or in real time](https://www.shipengine.com/docs/tracking/)
      - [Validate mailing addresses anywhere on Earth](https://www.shipengine.com/docs/addresses/validation/)


    ## Shipping Labels for Every Major Carrier

    ShipEngine makes it easy to [create shipping labels for any
    carrier](https://www.shipengine.com/docs/labels/create-a-label/) and
    [download them](https://www.shipengine.com/docs/labels/downloading/) in a
    [variety of file formats](https://www.shipengine.com/docs/labels/formats/).
    You can even customize labels with your own
    [messages](https://www.shipengine.com/docs/labels/messages/) and
    [images](https://www.shipengine.com/docs/labels/branding/).



    ## Real-Time Package Tracking

    With ShipEngine you can [get the current status of a
    package](https://www.shipengine.com/docs/tracking/) or [subscribe to
    real-time tracking
    updates](https://www.shipengine.com/docs/tracking/webhooks/) via webhooks.
    You can also create [custimized tracking
    pages](https://www.shipengine.com/docs/tracking/branded-tracking-page/) with
    your own branding so your customers will always know where their package is.



    ## Compare Shipping Costs Across Carriers

    Make sure you ship as cost-effectively as possible by [comparing rates
    across carriers](https://www.shipengine.com/docs/rates/get-shipment-rates/)
    using the ShipEngine Rates API. Or if you don't know the full shipment
    details yet, then you can [get rate
    estimates](https://www.shipengine.com/docs/rates/estimate/) with limited
    address info.



    ## Worldwide Address Validation

    ShipEngine supports [address
    validation](https://www.shipengine.com/docs/addresses/validation/) for
    virtually [every country on
    Earth](https://www.shipengine.com/docs/addresses/validation/countries/),
    including the United States, Canada, Great Britain, Australia, Germany,
    France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.
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: []
                empty_fields:
                  summary: Empty Fields
                  description: A response for an `unverified` API Call with error message
                  value:
                    - status: unverified
                      original_address:
                        name: null
                        phone: null
                        company_name: null
                        address_line1: null
                        address_line2: null
                        address_line3: null
                        city_locality: null
                        state_province: null
                        postal_code: null
                        country_code: null
                        address_residential_indicator: unknown
                      matched_address: null
                      messages:
                        - code: a1001
                          message: >-
                            country_code is not currently a supported country
                            please check the documentation for acceptable
                            2-letter country codes.
                          type: error
                          detail_code: unsupported_country
        '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](https://www.shipengine.com/docs/reference/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](https://www.shipengine.com/docs/reference/get-batch-by-id/) 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](https://www.shipengine.com/docs/reference/get-batch-by-id/) 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
      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
      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
      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
      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/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.
      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.
      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](https://www.shipengine.com/docs/carriers/setup/)

      in the API dashboard, and then [begin creating
      labels](https://www.shipengine.com/docs/shipping/use-a-carrier-service/).
    get:
      summary: List labels
      description: >
        This endpoint returns a list of labels that you've
        [created](https://www.shipengine.com/docs/labels/create-a-label/). 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](https://www.shipengine.com/docs/shipping/use-a-carrier-service/)
        - description: >-
            Only return labels for a specific [carrier
            account](https://www.shipengine.com/docs/carriers/setup/)
          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](https://www.shipengine.com/docs/labels/bulk/)
          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
        - description: >-
            Only return labels that originate from a specific
            [warehouse](https://www.shipengine.com/docs/shipping/ship-from-a-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'
        '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/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: Purchase Label from Rate Shopper
    description: >-
      Purchase and print a label using Rate Shopper to automatically select
      carrier and service
    parameters:
      - name: rate_shopper_id
        in: path
        required: true
        description: >
          The rate selection strategy for the Rate Shopper. This determines
          which carrier

          and service will be automatically selected from your wallet carriers
          based on

          the rates returned for the shipment.
        schema:
          $ref: '#/components/schemas/rate_attributes'
    post:
      summary: Purchase Label from Rate Shopper
      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 your specified rate selection strategy (cheapest, fastest, or
        best_value).

        For more information about this in the [rates
        documentation](https://www.shipengine.com/docs/rates/#about-the-response).
      tags:
        - labels
      operationId: create_label_from_rate_shopper
      parameters:
        - name: rate_shopper_id
          in: path
          required: true
          description: >
            The rate selection strategy for the Rate Shopper. This determines
            which carrier

            and service will be automatically selected from your wallet carriers
            based on

            the rates returned for the shipment.
          schema:
            $ref: '#/components/schemas/rate_attributes'
      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: ''
                    carrier_id: se-456789
                    service_code: usps_priority_mail
                    package_code: package
                    voided: false
                    voided_at: null
                    label_format: pdf
                    label_layout: 4x6
                    trackable: true
                    label_image_id: null
                    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: null
                    insurance_claim: null
                    packages: []
                    charge_event: carrier_default
                    rate_shopper_id: cheapest
        '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/{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/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'
        '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/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:
                      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:
                        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/{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/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](https://www.shipengine.com/docs/reference/list-shipments/).
    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
      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
  /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](https://www.shipengine.com/docs/carriers/setup/), 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](https://www.shipengine.com/docs/carriers/setup/), 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](https://www.shipengine.com/docs/carriers/setup/), 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](https://www.shipengine.com/docs/reference/create-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](https://www.shipengine.com/docs/reference/create-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'
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
      type: object
      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](https://www.shipengine.com/docs/carriers/setup/) 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
      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](https://www.shipengine.com/docs/carriers/setup/),
        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
      type: object
      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
      type: object
      description: A link to a related resource
      additionalProperties: false
      required:
        - href
      allOf:
        - $ref: '#/components/schemas/optional_link'
    optional_link:
      title: optional_link
      type: object
      description: >-
        A link to a related resource, or an empty object if there is no resource
        to link to
      additionalProperties: false
      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: 'http://api.shipengine.com/v1/labels/se-28529731'
      description: A URL
    create_account_settings_image_request_body:
      title: create_account_settings_image_request_body
      type: object
      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
      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.
    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
      type: object
      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
      type: object
      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.
      additionalProperties: false
      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](https://www.shipengine.com/docs/addresses/validation/) 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
      type: object
      description: |
        Any residential or business mailing address, anywhere in the world.
      required:
        - address_line1
        - city_locality
        - state_province
        - country_code
      additionalProperties: false
      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:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The original address that was sent for validation
        matched_address:
          nullable: true
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/address'
          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
      type: object
      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
      additionalProperties: false
      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:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/address_validation_detail_code'
    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:
          nullable: true
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          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:
          errors: null
          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:
            type: string
            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:
            type: string
            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:
              type: string
              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
      type: object
      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
      type: object
      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
      type: object
      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
      type: object
      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:
          type: string
          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
      type: object
      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
      additionalProperties: false
      required:
        - carriers
      properties:
        carriers:
          type: array
          readOnly: true
          items:
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/carrier'
          description: The carrier 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](https://www.shipengine.com/docs/carriers/setup/) 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:
          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.
        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.
    package_type:
      title: package_type
      type: object
      description: A package type that a carrier supports for shipment.
      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:
          allOf:
            - $ref: '#/components/schemas/package_code'
        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_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](https://www.shipengine.com/docs/reference/list-carrier-packages/),
        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
      type: object
      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
      type: object
      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/package_type'
            description: Custom Package Type items
          description: An array of custom 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
      type: object
      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
      type: object
      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
      type: object
      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
      type: object
      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
      type: object
      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
      type: object
      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
      type: object
      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'
    label_download_type:
      title: label_download_type
      type: string
      enum:
        - url
        - inline
      description: >
        There are two different ways to [download a
        label](https://www.shipengine.com/docs/labels/downloading/):


        |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://[YOUR ENDPOINT ID].x.requestbin.com'
          description: The url that the webhook sends the request to
        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
      min_length: 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://[YOUR ENDPOINT ID].x.requestbin.com'
          description: The url that the webhook sends the request to
        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
      type: object
      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
      type: object
      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://[YOUR ENDPOINT ID].x.requestbin.com'
          description: The url that the wehbook sends the request
        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
      type: object
      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
      type: object
      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
      type: object
      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](https://www.shipengine.com/docs/labels/create-a-label/) can be
        in.


        |Status       |Description

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

        |`processing` |When labels are created in a
        [batch](https://www.shipengine.com/docs/labels/bulk/), 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](https://www.shipengine.com/docs/labels/voiding/)
    service_code:
      title: service_code
      type: string
      pattern: '^[a-z0-9]+(_[a-z0-9-]+)* ?$'
      example: usps_first_class_mail
      description: >
        A [carrier
        service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/),
        such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`,
        etc.
    list_labels_response_body:
      title: list_labels_response_body
      type: object
      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](https://www.shipengine.com/docs/labels/create-a-label/)
              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](https://www.shipengine.com/docs/labels/create-a-label/),
                  or you can [create your own
                  shipment](https://www.shipengine.com/docs/shipping/create-a-shipment/)
                  and then [use it to print a
                  label](https://www.shipengine.com/docs/labels/create-from-shipment/)
              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](https://www.shipengine.com/docs/labels/bulk/), 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](https://www.shipengine.com/docs/carriers/setup/) 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](https://www.shipengine.com/docs/shipping/use-a-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](https://www.shipengine.com/docs/reference/list-carrier-packages/),
                  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](https://www.shipengine.com/docs/labels/voiding/)
              voided_at:
                nullable: true
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/date_time'
                description: >
                  The date and time that the label was
                  [voided](https://www.shipengine.com/docs/labels/voiding/), 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:
                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](https://www.shipengine.com/docs/carriers/setup/) 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 that is required for this
                  shipment.
              label_download:
                allOf:
                  - $ref: '#/components/schemas/label_download'
                readOnly: true
              form_download:
                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:
                readOnly: true
                nullable: true
                allOf:
                  - $ref: '#/components/schemas/optional_link'
                description: The QR code download for the package
              paperless_download:
                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:
                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
              void_type:
                nullable: true
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/void_type'
                description: >
                  Indicates how the label was voided. This field is `null` if
                  the label has not been voided.
                example: manual
              refund_details:
                nullable: true
                readOnly: true
                allOf:
                  - $ref: '#/components/schemas/refund_details'
                description: >
                  Information about the Refund Assist request for this label.
                  This field is `null` if the label is not eligible for Refund
                  Assist.
      allOf:
        - $ref: '#/components/schemas/paged_list_response_body'
    create_label_request_body:
      title: create_label_request_body
      type: object
      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'
    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](https://www.shipengine.com/docs/labels/create-a-label/) 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:
          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](https://www.shipengine.com/docs/shipping/use-a-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
        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](https://www.shipengine.com/docs/reference/create-warehouse/).
            Then you can simply specify the `warehouse_id` rather than the
            complete address each time.
        warehouse_id:
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The
            [warehouse](https://www.shipengine.com/docs/shipping/ship-from-a-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 that is required for this
            shipment.
        customs:
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/international_shipment_options'
          description: >
            Customs information.  This is usually only needed for international
            shipments.
        advanced_options:
          allOf:
            - $ref: '#/components/schemas/advanced_shipment_options'
          description: Advanced shipment options.  These are entirely optional.
        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
      type: object
      additionalProperties: false
      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.
      additionalProperties: false
      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 assign 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
      type: object
      additionalProperties: false
      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.
      additionalProperties: false
      properties:
        instructions:
          type: string
          minLength: 1
          nullable: true
          description: |
            Additional text about how to handle the shipment at this address.
    shipping_address:
      title: shipping_address
      type: object
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/address'
        - $ref: '#/components/schemas/partial_shipping_address'
    delivery_confirmation:
      title: delivery_confirmation
      type: string
      enum:
        - none
        - delivery
        - signature
        - adult_signature
        - 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
      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:
          type: string
          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
        invoice_additional_details:
          type: object
          allOf:
            - $ref: '#/components/schemas/invoice_additional_details'
        importer_of_record:
          type: object
          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
        - 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
      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:
          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
          exclusiveMinimum: true
          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](https://www.shipengine.com/docs/shipping/bill-to-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:
          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:
          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:
          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](https://www.shipengine.com/docs/shipping/ups-ground-freight/).
            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:
          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
        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
              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
          description: >-
            Indicates that the contents of the package are fragile and should be
            handled with care.
        delivery-as-addressed:
          type: boolean
          default: false
          description: >-
            Instructs the carrier to deliver the package only to the exact
            address provided.
        return-after-first-attempt:
          type: boolean
          default: false
          description: >-
            Ensures the shipment is immediately flagged for return to the sender
            if the initial delivery attempt fails.
        regulated_content_type:
          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.
    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
          type: number
    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
        - 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](https://www.shipengine.com/docs/reference/list-carrier-packages/)
        package_code:
          allOf:
            - $ref: '#/components/schemas/package_code'
          description: >
            The [package
            type](https://www.shipengine.com/docs/reference/list-carrier-packages/),
            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](https://www.shipengine.com/docs/reference/list-carrier-packages/)
        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.
        tracking_number:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/tracking_number'
          description: >
            The tracking number for the package.  The format depends on the
            carrier.
        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:
          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'
        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
      type: object
      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](https://www.shipengine.com/docs/labels/create-a-label/) 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](https://www.shipengine.com/docs/labels/create-a-label/), or
            you can [create your own
            shipment](https://www.shipengine.com/docs/shipping/create-a-shipment/)
            and then [use it to print a
            label](https://www.shipengine.com/docs/labels/create-from-shipment/)
        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](https://www.shipengine.com/docs/labels/bulk/), 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](https://www.shipengine.com/docs/carriers/setup/) 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](https://www.shipengine.com/docs/shipping/use-a-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](https://www.shipengine.com/docs/reference/list-carrier-packages/),
            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](https://www.shipengine.com/docs/labels/voiding/)
        voided_at:
          nullable: true
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/date_time'
          description: >
            The date and time that the label was
            [voided](https://www.shipengine.com/docs/labels/voiding/), 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:
          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](https://www.shipengine.com/docs/carriers/setup/) 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 that is required for this
            shipment.
        label_download:
          allOf:
            - $ref: '#/components/schemas/label_download'
          readOnly: true
        form_download:
          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:
          readOnly: true
          nullable: true
          allOf:
            - $ref: '#/components/schemas/optional_link'
          description: The QR code download for the package
        paperless_download:
          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:
          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
        void_type:
          nullable: true
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/void_type'
          description: >
            Indicates how the label was voided. This field is `null` if the
            label has not been voided.
          example: manual
        refund_details:
          nullable: true
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/refund_details'
          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
      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:
        - shipment_id
        - carrier_id
        - service_code
        - ship_date
        - created_at
        - modified_at
        - shipment_status
        - ship_to
        - ship_from
        - warehouse_id
        - return_to
        - confirmation
        - customs
        - advanced_options
        - 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](https://www.shipengine.com/docs/shipping/use-a-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
        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](https://www.shipengine.com/docs/reference/create-warehouse/).
            Then you can simply specify the `warehouse_id` rather than the
            complete address each time.
        warehouse_id:
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The
            [warehouse](https://www.shipengine.com/docs/shipping/ship-from-a-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 that is required for this
            shipment.
        customs:
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/international_shipment_options'
          description: >
            Customs information.  This is usually only needed for international
            shipments.
        advanced_options:
          allOf:
            - $ref: '#/components/schemas/advanced_shipment_options'
          description: Advanced shipment options.  These are entirely optional.
        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'
        carrier_description:
          type: string
          description: A rate detail description defined by a carrier
        carrier_billing_code:
          type: string
          description: A rate detail code defined by a carrier
        carrier_memo:
          type: string
          description: Contains any additional information
        amount:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
        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
          description: >-
            The source of the billing information. This is typically the
            carrier, but could be a third party, e.g insurance
    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
      description: The possible rate detail type values
    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
      description: Type of a tax added to shipping cost
    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](https://www.shipengine.com/docs/labels/create-a-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](https://www.shipengine.com/docs/reference/list-carrier-packages/),
            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:
          readOnly: true
          nullable: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The amount that was originally paid for the label
        amount_requested:
          readOnly: true
          nullable: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The amount requested to be refunded
        amount_approved:
          readOnly: true
          nullable: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The amount approved for refund by the carrier
        amount_credited:
          readOnly: true
          nullable: true
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          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
      type: object
      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
      type: object
      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
    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
      type: object
      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:
          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](https://www.shipengine.com/docs/reference/create-warehouse/).
            Then you can simply specify the `warehouse_id` rather than the
            complete address each time.
        warehouse_id:
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: >
            The
            [warehouse](https://www.shipengine.com/docs/shipping/ship-from-a-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 that is required for this
            shipment.
        customs:
          nullable: true
          default: null
          allOf:
            - $ref: '#/components/schemas/international_shipment_options'
          description: >
            Customs information.  This is usually only needed for international
            shipments.
        advanced_options:
          allOf:
            - $ref: '#/components/schemas/advanced_shipment_options'
          description: Advanced shipment options.  These are entirely optional.
        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
      type: object
      description: >
        The response from creating a label using the Rate Shopper. Includes all
        standard

        label information plus the rate_shopper_id indicating which strategy was
        used.
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/label'
      properties:
        rate_shopper_id:
          description: >
            The rate selection strategy that was used to create this label. This
            will

            match the rate_shopper_id provided in the request path.
          readOnly: true
          allOf:
            - title: rate_attributes
              type: string
              enum:
                - best_value
                - cheapest
                - fastest
              description: Optional attributes that indicate the most profitable rates
    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
      type: object
      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
      type: object
      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:
          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
      type: object
      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
      type: object
      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](https://www.shipengine.com/docs/carriers/setup/) 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.
        reason_code:
          readOnly: true
          type: string
          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
      type: object
      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
      type: object
      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'
            description: Custom Package Types items
          description: An array of custom package types
    create_package_type_request_body:
      title: create_package_type_request_body
      type: object
      description: A create package type request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/package_type'
    create_package_type_response_body:
      title: create_package_type_response_body
      type: object
      description: A create package type response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/package_type'
    get_package_type_by_id_response_body:
      title: get_package_type_by_id_response_body
      type: object
      description: A get package type by id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/package_type'
    update_package_type_request_body:
      title: update_package_type_request_body
      type: object
      description: An update package type request body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/package_type'
    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
      type: object
      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
      type: object
      description: A pickup response body
      required:
        - pickup
        - pickup_id
        - label_ids
        - created_at
        - carrier_id
        - warehouse_id
        - pickup_address
        - contact_details
        - 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
      type: object
      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
      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
      type: object
      description: A rate shipment response body
      required:
        - rate_response
        - shipment_id
        - ship_date
        - created_at
        - modified_at
        - shipment_status
        - return_to
        - confirmation
        - customs
        - advanced_options
        - 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:
          type: string
          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:
          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
      type: object
      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:
          type: string
          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
      type: object
      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:
            type: string
            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:
          type: string
          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:
          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](https://www.shipengine.com/docs/carriers/setup/), 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
      type: object
      description: A rate response body
      required:
        - rates
        - invalid_rates
        - rate_request_id
        - shipment_id
        - created_at
        - status
        - errors
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/rate'
    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:
              type: string
              allOf:
                - $ref: '#/components/schemas/postal_code'
            country_code:
              type: string
              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](https://www.shipengine.com/docs/carriers/setup/)
                    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](https://www.shipengine.com/docs/carriers/setup/)
                  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: '????'
        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
      type: object
      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
      type: object
      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](https://www.shipengine.com/docs/addresses/validation/) 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
      type: object
      description: A get shipment by id response body
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/shipment'
    update_shipment_request_body:
      title: update_shipment_request_body
      type: object
      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
      type: object
      description: An update shipment response body
      required:
        - errors
        - has_errors
        - address_validation
        - shipment_id
        - carrier_id
        - service_code
        - ship_date
        - created_at
        - shipment_status
        - ship_to
        - ship_from
        - return_to
        - confirmation
        - customs
        - advanced_options
        - insurance_provider
        - tags
        - packages
        - total_weight
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/create_and_validate_shipment'
    list_shipment_rates_response_body:
      title: list_shipment_rates_response_body
      type: object
      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
      type: object
      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:
            type: string
    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
      type: object
      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
      type: object
      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
      type: object
      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
      type: object
      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
      type: object
      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
      type: object
      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
  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://www.shipengine.com/docs/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.](https://www.shipengine.com/docs/addresses/validation/)


      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.
    externalDocs:
      url: 'https://www.shipengine.com/docs/addresses/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.
    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.](https://www.shipengine.com/docs/carriers/setup/)
    x-displayName: Carrier Accounts
  - name: carriers
    description: |
      carriers
    x-displayName: Carriers
  - name: downloads
    description: |
      downloads
    x-displayName: Downloads
  - 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](https://www.shipengine.com/docs/carriers/setup/) in the API
      dashboard, and then [begin creating
      labels](https://www.shipengine.com/docs/shipping/use-a-carrier-service/).
    externalDocs:
      url: 'https://www.shipengine.com/docs/labels/create-a-label/'
      description: >-
        Follow this quick start guide to create your first shipping label with
        ShipEngine
    x-displayName: Labels
  - 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](https://www.shipengine.com/docs/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.
    externalDocs:
      url: 'https://www.shipengine.com/docs/rates/'
      description: >
        This quick start guide shows you how to get shipping rates for multiple
        carriers so you can choose the fastest, cheapest, or most reliable
        option.
    x-displayName: Rates
  - name: service_points
    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](https://www.shipengine.com/docs/labels/create-a-label/), or
      [creating a
      manifest](https://www.shipengine.com/docs/shipping/manifests/).  It's also
      essential for [getting shipping
      rates](https://www.shipengine.com/docs/rates/).
    externalDocs:
      url: 'https://www.shipengine.com/docs/shipping/create-a-shipment/'
      description: >
        Learn about the shipment object model concept, and how to persist and
        re-use shipment data inside ShipEngine.
    x-displayName: Shipments
  - name: tags
    description: |
      tags
    x-displayName: Tags
  - name: tokens
    x-displayName: Tokens
  - name: tracking
    description: >
      [Track packages](https://www.shipengine.com/docs/tracking/) 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.
    externalDocs:
      url: 'https://www.shipengine.com/docs/tracking/'
      description: >-
        Learn how to use ShipEngine to track any package with a carrier and a
        tracking number
    x-displayName: Tracking
  - name: warehouses
    description: |
      warehouses
    x-displayName: Warehouses
  - name: webhooks
    description: >
      [Webhooks](https://www.shipengine.com/docs/tracking/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 stage
      changes.  This can include [parcel
      tracking](https://www.shipengine.com/docs/tracking/) events, notification
      of the completion of a [batch
      operation](https://www.shipengine.com/docs/labels/bulk/),  or new [salses
      orders](https://www.shipengine.com/docs/orders/).
    externalDocs:
      url: 'https://www.shipengine.com/docs/tracking/webhooks/'
      description: Learn how to setup webhooks and start listening to ShipEngine events.
    x-displayName: Webhooks
security:
  - api_key: []
externalDocs:
  url: 'https://www.shipengine.com/docs/'
  description: >
    ShipEngine's documentation is designed to help you start shipping as quickly
    as possible. With easy-to-follow tutorials, detailed reference docs, and
    ready-made recipes for common use cases, you'll see real results in no time
    at all.