openapi.yaml

openapi: 3.0.0
info:
  title: ShipEngine API
  version: 1.1.202209262209
  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/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
        - 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_body'
      responses:
        '200':
          description: The requested object creation was a success.
          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'
  '/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 `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
    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/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 webook 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'
        - 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
            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/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
      tags:
        - labels
      operationId: create_return_label
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_return_label_request_body'
      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/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/{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'
  '/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
      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: Carrier code used to retrieve tracking information
        - name: tracking_number
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: '9405511899223197428490'
          description: The tracking number associated with a shipment
      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: Carrier code used to retrieve tracking information
        - name: tracking_number
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: '9405511899223197428490'
          description: The tracking number associated with a 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/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: Carrier code used to retrieve tracking information
        - name: tracking_number
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          example: '9405511899223197428490'
          description: The tracking number associated with a 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/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'
servers:
  - url: 'https://api.shipengine.com'
components:
  schemas:
    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.
        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`.
    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
    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
      description: The error code specified for the failed API Call
    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
        - phone
        - address_line1
        - city_locality
        - state_province
        - postal_code
        - country_code
        - address_residential_indicator
      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
        - warnings
        - completed
        - forms
        - count
        - batch_shipments_url
        - batch_labels_url
        - batch_errors_url
        - label_download
        - form_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
        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
        status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/batch_status'
    label_layout:
      title: label_layout
      type: string
      enum:
        - 4x6
        - letter
      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> `globegistics` <br> `imex` <br> `newgistics` <br> `ontrac` <br>
        `rr_donnelley` <br> `stamps_com` <br> `ups` <br> `usps`
    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.
    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.
    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
    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
    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'
    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_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'
    empty_response_body:
      title: empty_response_body
      type: string
      maxLength: 0
    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.
    display_scheme:
      title: display_scheme
      type: string
      enum:
        - label
        - qr_code
        - label_and_qr_code
      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:
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the carrier.
        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
          format: double
          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
        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
        supports_label_messages:
          type: boolean
          readOnly: true
          description: The carrier supports adding custom label messages to an order.
        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
    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
    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
          example: laptop_box
        dimensions:
          allOf:
            - $ref: '#/components/schemas/dimensions'
          description: The custom dimensions for the package.
        description:
          type: string
          example: Packaging for laptops
          nullable: true
          description: Provides a helpful description for the custom package.
    package_code:
      title: package_code
      type: string
      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
          format: double
          minimum: 0
          default: 0
          description: 'The length of the package, in the specified unit'
        width:
          type: number
          format: double
          minimum: 0
          default: 0
          description: 'The width of the package, in the specified unit'
        height:
          type: number
          format: double
          minimum: 0
          default: 0
          description: 'The length 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
          format: double
          minimum: 0
          description: 'The monetary amount, in the specified currency.'
    currency:
      title: currency
      type: string
      enum:
        - usd
        - cad
        - aud
        - gbp
        - eur
        - nzd
      description: |
        The currencies that are supported by ShipEngine.

        |Currency Code  | Description
        |---------------|-----------------------
        |`usd`          | United States Dollar
        |`cad`          | Canadian Dollar
        |`aud`          | Australian Dollar
        |`gbp`          | Great British Pound
        |`eur`          | Euro
        |`nzd`          | New Zealand Dollar
    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
        - globegistics
        - imex
        - newgistics
        - ontrac
        - purolator_canada
        - royal_mail
        - rr_donnelley
        - seko
        - sendle
        - stamps_com
        - ups
      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_globegistics_request_body'
        - $ref: '#/components/schemas/connect_imex_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
        - ftp_username
        - ftp_password
      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
        ftp_username:
          type: string
          minLength: 1
          description: FTP username
        ftp_password:
          type: string
          minLength: 1
          description: FTP password
    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_globegistics_request_body:
      title: connect_globegistics_request_body
      type: object
      description: A Globegistics 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_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_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
      required:
        - nickname
        - account_number
        - account_country_code
        - account_postal_code
        - first_name
        - last_name
        - company
        - address1
        - city
        - state
        - postal_code
        - country_code
        - email
        - phone
        - agree_to_technology_agreement
      additionalProperties: false
      properties:
        nickname:
          type: string
          minLength: 1
          description: Nickname
        account_number:
          type: string
          minLength: 1
          description: Account number
        account_country_code:
          type: string
          minLength: 1
          description: Account country code
        account_postal_code:
          type: string
          minLength: 1
          description: Account postal code
        title:
          type: string
          minLength: 1
          description: Title
        first_name:
          type: string
          minLength: 1
          description: First name
        last_name:
          type: string
          minLength: 1
          description: Last name
        company:
          type: string
          minLength: 1
          description: Company
        address1:
          type: string
          minLength: 1
          description: Address Line 1
        address2:
          type: string
          minLength: 1
          description: Address Line 2
        city:
          type: string
          minLength: 1
          description: City
        state:
          type: string
          minLength: 1
          description: State
        postal_code:
          type: string
          minLength: 1
          description: Postal code
        country_code:
          type: string
          minLength: 1
          description: Country code
        email:
          allOf:
            - $ref: '#/components/schemas/email'
          description: The email address
        phone:
          type: string
          minLength: 1
          description: Phone
        invoice:
          allOf:
            - $ref: '#/components/schemas/ups_invoice'
          description: The UPS invoice
        invoice_amount:
          format: double
          type: number
          description: The invoice amount
        invoice_currency_code:
          type: string
          description: The invoice currency code
        agree_to_technology_agreement:
          type: boolean
          description: >-
            The Agreement to the [UPS Technology
            Agreement](https://www.ups.com/assets/resources/media/UTA_with_EUR.pdf)
    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
          format: double
          minimum: 0
        invoice_currency_code:
          type: string
    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: >
        Determines how FedEx will pickup your packages


        |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
      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
    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
    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'
    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 webook event values
    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
    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
    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/)
              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) shippped. 
                  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.
              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`
              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.
              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:
                  $ref: '#/components/schemas/package'
      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.
    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'
      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:
      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/)
        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) shippped.  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.
        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`
        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.
        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:
            $ref: '#/components/schemas/package'
    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.
        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) shippped.  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/address'
          description: The recipient's mailing address
        ship_from:
          allOf:
            - $ref: '#/components/schemas/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/address'
          description: >
            The return address for this shipment.  Defaults to the `ship_from`
            address.
        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.
        origin_type:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/origin_type'
          description: >-
            Indicates if the package will be picked up or dropped off by the
            carrier
        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
    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
        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
      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.
    identifier_type:
      title: identifier_type
      type: string
      enum:
        - vat
        - eori
        - ssn
        - ein
        - tin
        - ioss
        - pan
        - voec
      description: >
        Determines how FedEx will pickup your packages


        |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).
    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.
    shipment_status:
      title: shipment_status
      type: string
      enum:
        - pending
        - processing
        - label_purchased
        - cancelled
      description: The possible shipment status values
    delivery_confirmation:
      title: delivery_confirmation
      type: string
      enum:
        - none
        - delivery
        - signature
        - adult_signature
        - direct_signature
        - delivery_mailed
        - verbal_confirmation
      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.
        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.
        customs_items:
          type: array
          default: []
          minItems: 0
          description: Customs declarations for each item in the shipment.
          items:
            $ref: '#/components/schemas/customs_item'
    package_contents:
      title: package_contents
      type: string
      enum:
        - merchandise
        - documents
        - gift
        - returned_goods
        - sample
      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
    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:
          allOf:
            - $ref: '#/components/schemas/monetary_value'
          description: The declared customs value of each item
        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
    advanced_shipment_options:
      title: advanced_shipment_options
      type: object
      description: Advanced shipment options
      additionalProperties: false
      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'
        shipper_release:
          type: boolean
          nullable: true
          default: null
        collect_on_delivery:
          $ref: '#/components/schemas/collect_on_delivery'
    bill_to_party:
      title: bill_to_party
      type: string
      enum:
        - recipient
        - third_party
      description: The possible bill to party values
    weight:
      title: weight
      type: object
      description: The weight of a package
      required:
        - value
        - unit
      additionalProperties: false
      properties:
        value:
          type: number
          format: double
          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
    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
          format: double
          type: number
    insurance_provider:
      title: insurance_provider
      type: string
      enum:
        - none
        - shipsurance
        - carrier
        - third_party
      description: The possible insurance provider 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:
        name:
          type: string
          minLength: 1
          example: Fragile
          description: The tag name.
    package:
      title: package
      type: object
      description: >
        A package associated with 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 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_messages:
          allOf:
            - $ref: '#/components/schemas/label_messages'
        external_package_id:
          type: string
          minLength: 1
          description: An external package id.
        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
        sequence:
          readOnly: true
          format: int32
          type: integer
          description: Package sequence
    tracking_number:
      title: tracking_number
      type: string
      minLength: 1
      example: 1Z932R800392060079
      description: A tracking number for a package. The format depends on the carrier.
    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.
    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
    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.<br><br>This is the default if `label_download_type` is
        unspecified.

        |`inline`            |You will receive the Base64-encoded label as part
        of the response. No need for a second request to download the label.
    image_id:
      title: image_id
      type: string
      minLength: 4
      example: img_DtBXupDBxREpHnwEXhTfgK
      description: Used to identify an image resource.
    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.
    tracking_status:
      title: tracking_status
      type: string
      enum:
        - unknown
        - in_transit
        - error
        - delivered
      description: The different statuses that can apply to a shipment.
    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
        - ship_date
        - created_at
        - shipment_cost
        - insurance_cost
        - tracking_number
        - is_international
        - batch_id
        - carrier_id
        - service_code
        - voided
        - voided_at
        - label_image_id
        - label_format
        - label_layout
        - trackable
        - carrier_code
        - tracking_status
        - label_download
        - form_download
        - insurance_claim
        - packages
        - is_return_label
        - rma_number
        - charge_event
        - package_code
        - display_scheme
      allOf:
        - $ref: '#/components/schemas/label'
    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'
    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:
          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'
    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:
          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.
    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
        - estimated_delivery_date
        - 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'
        carrier_code:
          allOf:
            - $ref: '#/components/schemas/carrier_code'
        carrier_id:
          allOf:
            - $ref: '#/components/schemas/se_id'
        status_description:
          type: string
          readOnly: true
          example: Delivered
          minLength: 0
          description: Status 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
      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
    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'
        status_description:
          type: string
          readOnly: true
          minLength: 1
          example: In Transit
          description: Event Status 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.
    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
          description: Indicates whether the attempt to void the label was successful
        message:
          type: string
          minLength: 0
          readOnly: true
          example: Request for refund submitted.  This label has been voided.
    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/shipment_request'
      allOf:
        - $ref: '#/components/schemas/rate_request_options'
    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
    shipment_request:
      title: 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
    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'
            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
        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
          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:
          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'
    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
          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:
          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
    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
            address_line2:
              type: string
            address_line3:
              type: string
            city_locality:
              type: string
            state_province:
              type: string
            postal_code:
              type: string
            country_code:
              type: string
        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 latitude 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
    list_service_points_response_body:
      title: list_service_points_response_body
      type: object
      description: A list service points response body
      properties:
        service_points:
          type: array
          items:
            type: object
            properties:
              carrier_code:
                type: string
                example: chronopost
              service_codes:
                type: array
                items:
                  type: string
                  example: chronoclassic
              service_point_id:
                type: string
                example: '614940'
              address:
                type: object
                properties:
                  phone_number:
                    type: string
                    example: 555-555-5555
                  company_name:
                    type: string
                    example: My fancy company name
                  description:
                    type: string
                    example: This is a description of the service point
                  geo:
                    type: object
                    properties:
                      lat:
                        format: double
                        type: number
                        example: 48.842608
                      long:
                        format: double
                        type: number
                        example: 0.032875
                  address_line1:
                    type: string
                    example: PLACE DU CANADA
                  city_locality:
                    type: string
                    example: TRUN
                  state_province:
                    type: string
                    example: TRUN
                  postal_code:
                    type: string
                    example: '61160'
                  country_code:
                    type: string
                    example: FR
              hours_of_operation:
                type: object
                properties:
                  monday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                        close:
                          type: string
                          example: '12:00'
                  tuesday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                        close:
                          type: string
                          example: '12:00'
                  wednesday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                        close:
                          type: string
                          example: '12:00'
                  thursday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                        close:
                          type: string
                          example: '12:00'
                  friday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                        close:
                          type: string
                          example: '12:00'
                  saturday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                        close:
                          type: string
                          example: '12:00'
                  sunday:
                    type: array
                    items:
                      type: object
                      properties:
                        open:
                          type: string
                          example: '09:15'
                        close:
                          type: string
                          example: '12:00'
              features:
                type: array
                items:
                  type: string
                  enum:
                    - drop_off_point
                    - pickup_point
                    - print_services
                    - after_hours_locker
                    - after_hours_dropbox
        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:
              type: string
              example: chronopost
            service_codes:
              type: array
              items:
                type: string
            service_point_id:
              type: string
              example: '614940'
            address:
              type: object
              properties:
                phone_number:
                  type: string
                  example: 555-555-5555
                company_name:
                  type: string
                  example: My fancy company name
                description:
                  type: string
                  example: This is a description of the service point
                geo:
                  type: object
                  properties:
                    lat:
                      format: double
                      type: number
                      example: 48.842608
                    long:
                      format: double
                      type: number
                      example: 0.032875
                address_line1:
                  type: string
                  example: PLACE DU CANADA
                city_locality:
                  type: string
                  example: TRUN
                state_province:
                  type: string
                  example: TRUN
                postal_code:
                  type: string
                  example: '61160'
                country_code:
                  type: string
                  example: FR
            hours_of_operation:
              type: object
              properties:
                monday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                      close:
                        type: string
                        example: '12:00'
                tuesday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                      close:
                        type: string
                        example: '12:00'
                wednesday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                      close:
                        type: string
                        example: '12:00'
                thursday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                      close:
                        type: string
                        example: '12:00'
                friday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                      close:
                        type: string
                        example: '12:00'
                saturday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                      close:
                        type: string
                        example: '12:00'
                sunday:
                  type: array
                  items:
                    type: object
                    properties:
                      open:
                        type: string
                        example: '09:15'
                      close:
                        type: string
                        example: '12:00'
            features:
              type: array
              items:
                type: string
                enum:
                  - drop_off_point
                  - pickup_point
                  - print_services
                  - after_hours_locker
                  - after_hours_dropbox
    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'
    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.
    tag_shipment_response_body:
      title: tag_shipment_response_body
      type: object
      description: A shipment add tag response body
      required:
        - shipment_id
        - tag
      additionalProperties: false
      properties:
        shipment_id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/se_id'
          description: A string that uniquely identifies the shipment
        tag:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/tag'
          description: The tag that is now associated with this shipment
    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_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
        - estimated_delivery_date
        - 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
        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'
  responses:
    400_error_response:
      description: The request contained errors.
      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'
    404_error_response:
      description: The specified resource does not exist.
      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: 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: |
      carrier accounts
    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.