openapi: 3.1.0
info:
  title: Shippo external API.
  version: '2018-02-08'
  x-logo:
    url: https://docs.goshippo.com/images/shippo-logo.svg
  contact:
    name: Shippo Developer Platform
    url: https://goshippo.com/contact/
  description: Use this API to integrate with the Shippo service
security:
  - APIKeyHeader: []
servers:
  - url: https://api.goshippo.com
paths:
  /carrier_accounts:
    get:
      description: >-
        Returns a list of all carrier accounts connected to your Shippo account.
        These carrier accounts include both Shippo carrier accounts and your own
        carrier accounts that you have connected to your Shippo account.


        Additionally, you can get information about the service levels
        associated with each carrier account by passing in the
        `?service_levels=true` query parameter. <br>

        Using it appends the property `service_levels` to each carrier account.
        <br>

        By default, if the query parameter is omitted, the `service_levels`
        property will not be included in the response.
      operationId: ListCarrierAccounts
      parameters:
        - description: >-
            Appends the property `service_levels` to each returned carrier
            account
          in: query
          name: service_levels
          required: false
          schema:
            type: boolean
        - description: Filter the response by the specified carrier
          in: query
          name: carrier
          required: false
          schema:
            $ref: '#/components/schemas/CarriersEnum'
        - description: Filter the response by the specified carrier account Id
          in: query
          name: account_id
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/PageNumberQueryParam'
        - $ref: '#/components/parameters/ResultsPerPageDefault5QueryParam'
        - $ref: '#/components/parameters/ShippoApiVersionHeader'
      responses:
        '200':
          $ref: '#/components/responses/carrierAccountPaginatedResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
      summary: List all carrier accounts
      tags:
        - Carrier Accounts
      x-code-samples:
        - label: cURL
          lang: cURL
          source: >-
            curl https://api.goshippo.com/carrier_accounts?service_levels=true \

            -H "Authorization: ShippoToken
            shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
    post:
      description: >-
        Creates a new carrier account or connects an existing carrier account to
        the Shippo account.
      operationId: CreateCarrierAccount
      parameters:
        - $ref: '#/components/parameters/ShippoApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectExistingOwnAccountRequest'
        description: Examples.
        x-examples:
          application/json:
            fedex-existing-account-example:
              summary: Connect an existing Fedex account to Shippo
              value:
                account_id: 293235673
                carrier: fedex
                metadata: FedEx Account
                parameters:
                  use_multi_factor_registration: true
                  first_name: Tom
                  last_name: Monk
                  phone_number: 1234567890
                  from_address_st: 20 FED EX PKWY
                  from_address_city: Beverly Hills
                  from_address_state: CA
                  from_address_zip: 90210
                  from_address_country_iso2: US
                  verification_option: SMS
                test: false
            fedex-existing-account-invoice-example:
              summary: >-
                Connect an existing Fedex account to Shippo using invoice
                verification
              value:
                account_id: 293235673
                carrier: fedex
                metadata: FedEx Account
                parameters:
                  use_multi_factor_registration: true
                  first_name: Tom
                  last_name: Monk
                  phone_number: 1234567890
                  from_address_st: 20 FED EX PKWY
                  from_address_city: Beverly Hills
                  from_address_state: CA
                  from_address_zip: 90210
                  from_address_country_iso2: US
                  verification_option: INVOICE
                  verification_invoice_number: 293235673
                  verification_invoice_date: '2022-10-09'
                  verification_invoice_amount: 2323.22
                  verification_invoice_currency: USD
                test: false
            ups-existing-account-example:
              summary: Connect an existing UPS account to Shippo
              value:
                account_id: 123456
                active: true
                carrier: ups
                metadata: UPS Account
                parameters:
                  account_number: 94567e
                  aia_country_iso2: US
                  billing_address_city: San Francisco
                  billing_address_country_iso2: US
                  billing_address_state: CA
                  billing_address_street1: 731 Market St
                  billing_address_street2: STE 200
                  billing_address_zip: 94103
                  collec_country_iso2: US
                  collec_zip: 94103
                  company: Shippo
                  currency_code: USD
                  email: hippo@shippo.com
                  full_name: Shippo Meister
                  has_invoice: false
                  invoice_controlid: 1234
                  invoice_date: 20210529
                  invoice_number: 1112234
                  invoice_value: 11.23
                  phone: 1112223333
                  title: Manager
                  ups_agreements: true
                test: false
            ups-new-account-example:
              summary: Create a new UPS account
              value:
                account_id: 123456
                active: true
                carrier: ups
                metadata: UPS Account
                parameters:
                  billing_address_city: San Francisco
                  billing_address_country_iso2: US
                  billing_address_state: CA
                  billing_address_street1: 731 Market St
                  billing_address_street2: STE 200
                  billing_address_zip: 94103
                  company: Shippo
                  email: hippo@shippo.com
                  full_name: Shippo Meister
                  phone: 1112223333
                  pickup_address_city: San Francisco
                  pickup_address_country_iso2: US
                  pickup_address_same_as_billing_address: false
                  pickup_address_state: CA
                  pickup_address_street1: 731 Market St
                  pickup_address_street2: STE 200
                  pickup_address_zip: 94103
                  ups_agreements: true
                test: false
      responses:
        '201':
          $ref: '#/components/responses/carrierAccountResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
      summary: Create a new carrier account
      tags:
        - Carrier Accounts
      x-code-samples:
        - label: cURL
          lang: cURL
          source: >-
            curl --location --request POST
            'https://api.goshippo.com/carrier_accounts/' \

            --header 'Authorization: ShippoToken {{token}}' \

            --header 'Content-Type: application/json' \

            --data-raw '{
              "account_id": "string",
              "active": true,
              "carrier": "ups",
              "metadata": "UPS Account",
              "parameters": {
                "billing_address_city": "San Francisco",
                "billing_address_country_iso2": "US",
                "billing_address_state": "CA",
                "billing_address_street1": "731 Market St",
                "billing_address_street2": "STE 200",
                "billing_address_zip": "94103",
                "company": "Shippo",
                "email": "hippo@shippo.com",
                "full_name": "Thorn Hall",
                "phone": "1112223333",
                "pickup_address_city": "San Francisco",
                "pickup_address_country_iso2": "US",
                "pickup_address_same_as_billing_address": false,
                "pickup_address_state": "CA",
                "pickup_address_street1": "731 Market St",
                "pickup_address_street2": "STE 200",
                "pickup_address_zip": "94103",
                "ups_agreements": true
              },
              "test": false
            }'
  /carrier_accounts/{CarrierAccountId}:
    get:
      description: Returns an existing carrier account using an object ID.
      operationId: GetCarrierAccount
      parameters:
        - description: Object ID of the carrier account
          in: path
          name: CarrierAccountId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ShippoApiVersionHeader'
      responses:
        '200':
          $ref: '#/components/responses/carrierAccountResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
      summary: Retrieve a carrier account
      tags:
        - Carrier Accounts
      x-code-samples:
        - label: cURL
          lang: cURL
          source: >-
            curl
            https://api.goshippo.com/carrier_accounts/b741b99f95e841639b54272834bc478c
            \

            -H "Authorization: ShippoToken
            shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
    put:
      description: >-
        Updates an existing carrier account object. The account_id and carrier
        can't be updated. This is because they form the unique identifier
        together.
      operationId: UpdateCarrierAccount
      parameters:
        - description: Object ID of the carrier account
          in: path
          name: CarrierAccountId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ShippoApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierAccountUpdateRequest'
        description: Examples.
        x-examples:
          application/json:
            update-carrier-account:
              summary: Update a carrier account
              value:
                account_id: 123356
                active: true
                carrier: ups
                parameters: {}
      responses:
        '200':
          $ref: '#/components/responses/carrierAccountResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
      summary: Update a carrier account
      tags:
        - Carrier Accounts
      x-code-samples:
        - label: cURL
          lang: cURL
          source: >-
            curl
            https://api.goshippo.com/carrier_accounts/b741b99f95e841639b54272834bc478c/
            \

            -X PUT  \

            -H "Authorization: ShippoToken
            shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396" \

            -d parameters='{
                "meter": "123987"
            }'
  /carrier_accounts/{CarrierAccountObjectId}/signin/initiate:
    get:
      description: >-
        Used by client applications to setup or reconnect an existing carrier
        account with carriers that support OAuth 2.0
      summary: Connect an existing carrier account using OAuth 2.0
      operationId: InitiateOauth2Signin
      parameters:
        - description: The carrier account ID (UUID) to start a signin process.
          in: path
          name: CarrierAccountObjectId
          required: true
          schema:
            type: string
        - description: >-
            Callback URL. The URL that tells the authorization server where to
            send the user back to after they approve the request.
          in: query
          name: redirect_uri
          required: true
          schema:
            type: string
            format: uri
        - description: >-
            A random string generated by the consuming application and included
            in the request to prevent CSRF attacks. The consuming application
            checks that the same value is returned after the user authorizes
            Shippo.
          in: query
          name: state
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/ShippoApiVersionHeader'
      responses:
        '302':
          description: >-
            Redirects the browser to the carrier login page, with the needed
            parameters
          headers:
            Location:
              description: >-
                Carrier login page URI, with the needed parameters set as query
                string
              schema:
                type: string
                format: uri
              example: >-
                https://www.ups.com/lasso/signin?client_id=testClientID&redirect_uri=https://client.example.com/cb&response_type=code&scope=read&type=ups_com_api
        '400':
          description: Invalid parameters provided by the user
          content:
            application/json:
              schema:
                properties:
                  title:
                    type: string
                    example: Missing required parameter
                  detail:
                    type: string
                    example: redirect_uri
        '401':
          description: >-
            Invalid ShippoToken or unsupported carrier account provided by the
            user
          content:
            application/json:
              schema:
                properties:
                  title:
                    type: string
                    example: Unsupported OAuth Carrier Account
                  detail:
                    type: string
                    example: >-
                      The carrier account 3c49f998b1234a2097ea0911a7e95bea does
                      not support OAuth authorization
        '404':
          description: Invalid carrier account provided by the user
          content:
            application/json:
              schema:
                properties:
                  title:
                    type: string
                    example: Carrier Account not found
                  detail:
                    type: string
                    example: >-
                      Carrier Account not found for object_id:
                      3c49f998b1234a2097ea0911a7e95bea
      x-codeSamples:
        - label: cURL
          lang: cURL
          source: >-
            curl
            "https://api.goshippo.com/carrier_accounts/2ccf5af209bb484cb20190d9cadbb61c/signin/initiate?redirect_uri=https://client.example.com/cb&state=SplxlOBeZQQYbYS6WxSbIA"
            \

            -H "Authorization: ShippoToken
            shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
      tags:
        - Carrier Accounts
  /carrier_accounts/register/new:
    post:
      description: Adds a Shippo carrier account
      operationId: RegisterCarrierAccount
      parameters:
        - $ref: '#/components/parameters/ShippoApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CarrierAccountCanadaPostCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountChronopostCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountColissimoCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountCorreosCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountDeutschePostCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountDHLExpressCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountDpdDeCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountDPDUKCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountFedExCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountHermesUKCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountMondialRelayCreateRequest'
                - $ref: >-
                    #/components/schemas/CarrierAccountPosteItalianeCreateRequest
                - $ref: '#/components/schemas/CarrierAccountUPSCreateRequest'
                - $ref: '#/components/schemas/CarrierAccountUSPSCreateRequest'
        description: Examples.
      responses:
        '201':
          $ref: '#/components/responses/carrierAccountResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
      summary: Add a Shippo carrier account
      tags:
        - Carrier Accounts
      x-codeSamples:
        - label: cURL
          lang: cURL
          source: |-
            curl --location --request POST '/carrier_accounts/register/new' \
            --header 'Authorization: ShippoToken {{token}}' \
            --header 'Content-Type: application/json' \
            --data-raw '{
                "carrier": "canada_post",
                "parameters": {
                    "company": "Shippo",
                    "full_name": "Shippo Meister",
                    "email": "hippo@shippo.com",
                    "phone": "1112221122",
                    "canada_post_terms": true
                }
            }'
      x-speakeasy-name-override: register
  /carrier_accounts/reg-status:
    get:
      description: >-
        Returns the registration status for the given account for the given
        carrier
      operationId: GetCarrierRegistrationStatus
      parameters:
        - in: query
          description: filter by specific carrier
          name: carrier
          required: true
          schema:
            type: string
            enum:
              - ups
              - usps
              - canada_post
        - $ref: '#/components/parameters/ShippoApiVersionHeader'
      responses:
        '200':
          $ref: '#/components/responses/carrierAccountRegistrationStatusResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
      summary: Get Carrier Registration status
      tags:
        - Carrier Accounts
      x-speakeasy-name-override: getRegistrationStatus
  /carrier_accounts/{object_id}/documents:
    post:
      description: >-
        Uploads a letterhead or signature image file that can be added to
        commercial invoices by supporting carriers.
      summary: Upload letterhead and signature documents
      operationId: UploadDocument
      parameters:
        - name: object_id
          in: path
          required: true
          description: The object id of the account
          schema:
            type: string
            format: uuid
      requestBody:
        description: >-
          Document data required to upload a letterhead or signature document
          for a FedEx account.
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DocumentUploadRequest'
        required: true
      responses:
        '204':
          description: Document uploaded successfully
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Carrier Accounts
components:
  responses:
    carrierAccountRegistrationStatusResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CarrierAccountRegistrationStatus'
    carrierAccountPaginatedResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CarrierAccountPaginatedList'
    badRequestResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequest'
    carrierAccountResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CarrierAccountResponse'
  parameters:
    PageNumberQueryParam:
      description: The page number you want to select
      in: query
      name: page
      schema:
        type: integer
        format: int64
        default: 1
    ResultsPerPageQueryParam:
      description: The number of results to return per page (max 100)
      in: query
      name: results
      schema:
        type: integer
        format: int64
        maximum: 100
        default: 25
    ResultsPerPageDefault5QueryParam:
      description: The number of results to return per page (max 100, default 5)
      in: query
      name: results
      schema:
        type: integer
        format: int64
        maximum: 100
        default: 5
    ShippoApiVersionHeader:
      description: String used to pick a non-default API version to use
      in: header
      name: SHIPPO-API-VERSION
      schema:
        type: string
        example: '2018-02-08'
      x-speakeasy-globals-hidden: true
  securitySchemes:
    APIKeyHeader:
      in: header
      name: Authorization
      type: apiKey
  schemas:
    CarrierAccount:
      allOf:
        - $ref: '#/components/schemas/CarrierAccountBase'
        - properties:
            carrier_name:
              example: USPS
              description: >-
                Carrier name, see <a
                href="/shippoapi/public-api/carriers">Carriers</a><br>
            is_shippo_account:
              example: false
              type: boolean
            metadata:
              type: string
            object_id:
              example: 6aa34d5f6865448fbb1ee93636e98999
              type: string
              description: Unique identifier of the carrier account object.
            object_owner:
              example: bob+22@gmail.com
              type: string
              description: Username of the user who created the carrier account object.
            service_levels:
              items:
                $ref: '#/components/schemas/CarrierAccountServiceLevel'
              type: array
            test:
              example: false
              type: boolean
              description: Indicates whether the object has been created in test mode.
    CarrierAccountWithExtraInfo:
      allOf:
        - $ref: '#/components/schemas/CarrierAccount'
        - properties:
            object_info:
              type: object
              description: Holds internal state relevant to users.
              properties:
                authentication:
                  type: object
                  properties:
                    type:
                      type: string
                      description: Authentication method used by this account.
                      enum:
                        - default
                        - oauth
                    status:
                      type: string
                      description: >-
                        Current authentication status. Possible values:
                        'disconnected' (authorization lost, reconnect needed),
                        'connected' (authorized and active),
                        'authorization_pending' (awaiting initial authorization
                        flow).
                      enum:
                        - disconnected
                        - connected
                        - authorization_pending
    CarrierAccountServiceLevel:
      description: Contains details regarding the service level for the carrier account.
      properties:
        name:
          example: Priority Mail Express
          type: string
          description: >-
            Service level name, e.g. `Priority Mail` or `FedEx Ground®`. 

            A service level commonly defines the transit time of a Shipment
            (e.g., Express vs. Standard), along with other properties. 

            These names vary depending on the provider.<br>

            See <a href="/shippoapi/public-api/service-levels">Service
            Levels</a>.
        token:
          example: usps_priority_express
          type: string
          description: >-
            Service level token, e.g. `usps_priority` or `fedex_ground`.<br>

            See <a href="/shippoapi/public-api/service-levels">Service
            Levels</a>.
        supports_return_labels:
          example: true
          type: boolean
          description: Whether or not the service level supports return labels.
      type: object
    CarrierAccountBase:
      properties:
        account_id:
          description: >-
            Unique identifier of the account. Please check the <a
            href="https://docs.goshippo.com/docs/carriers/carrieraccounts/">carrier
            accounts tutorial</a> 

            page for the `account_id` per carrier.<br> 

            To protect account information, this field will be masked in any API
            response.
          example: '****'
          type: string
        active:
          type: boolean
          description: >-
            Determines whether the account is active. When creating a shipment,
            if no `carrier_accounts` are explicitly 

            passed Shippo will query all carrier accounts that have this field
            set. By default, this is set to True.
        carrier:
          example: usps
          type: string
          description: >-
            Carrier token, see <a
            href="/shippoapi/public-api/carriers">Carriers</a><br>

            Please check the <a
            href="https://docs.goshippo.com/docs/carriers/carrieraccounts/">carrier
            accounts tutorial</a> page for all supported carriers.
        parameters:
          oneOf:
            - $ref: '#/components/schemas/ConnectExistingOwnAccountParameters'
            - $ref: >-
                #/components/schemas/FedexConnectExistingOwnAccountParametersResponse
            - $ref: '#/components/schemas/UPSConnectExistingOwnAccountParameters'
      required:
        - carrier
        - account_id
      type: object
    CarrierAccountResponse:
      allOf:
        - $ref: '#/components/schemas/CarrierAccountBase'
        - properties:
            carrier_name:
              example: USPS
              description: >-
                Carrier name, see <a
                href="/shippoapi/public-api/carriers">Carriers</a><br>
            is_shippo_account:
              example: false
              type: boolean
            metadata:
              type: string
            object_id:
              example: 6aa34d5f6865448fbb1ee93636e98999
              type: string
              description: Unique identifier of the carrier account object.
            object_owner:
              example: bob+22@gmail.com
              type: string
              description: Username of the user who created the carrier account object.
            service_levels:
              items:
                $ref: '#/components/schemas/CarrierAccountServiceLevel'
              type: array
            test:
              example: false
              type: boolean
              description: Indicates whether the object has been created in test mode.
    BadRequest:
      additionalProperties: true
      type: object
    CarrierAccountPaginatedList:
      allOf:
        - $ref: '#/components/schemas/PaginatedList'
        - properties:
            results:
              items:
                $ref: '#/components/schemas/CarrierAccountWithExtraInfo'
              type: array
    CarrierAccountRegistrationStatus:
      properties:
        carrier_account:
          example: 99dc410d295b4a168993cc38809cb123
          type: string
        object_created:
          format: date-time
          type: string
        object_owner:
          example: tom@gmail.com
          type: string
        object_updated:
          format: date-time
          type: string
        status:
          example: PENDING_TERMS
          type: string
      type: object
    CarrierAccountCanadaPostCreateRequest:
      title: Shippo Canada Post account
      properties:
        carrier:
          example: canada_post
          type: string
        parameters:
          $ref: '#/components/schemas/CarrierAccountCanadaPostCreateParameters'
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountCanadaPostCreateParameters:
      properties:
        canada_post_terms:
          description: >-
            Whether or not the user agrees to Canada Post's terms. If passed in
            as false, request will fail with error 400
          type: boolean
        company:
          example: Shippo
          type: string
        email:
          example: hippo@shippo.com
          type: string
        full_name:
          example: Shippo Meister
          type: string
        phone:
          description: Needs to be a valid phone number and cannot be null
          example: '1112223333'
          type: string
      required:
        - company
        - phone
        - full_name
        - email
        - canada_post_terms
      type: object
    CarrierAccountChronopostCreateRequest:
      title: Shippo Chronopost account
      properties:
        carrier:
          example: chronopost
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountColissimoCreateRequest:
      title: Shippo Colissimo account
      properties:
        carrier:
          example: colissimo
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountCorreosCreateRequest:
      title: Shippo Correos account
      properties:
        carrier:
          example: correos
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountDeutschePostCreateRequest:
      title: Shippo Deutsche Post account
      properties:
        carrier:
          example: deustche_post
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountDHLExpressCreateRequest:
      title: Shippo DHL Express account
      properties:
        carrier:
          example: dhl_express
          type: string
        parameters:
          $ref: '#/components/schemas/CarrierAccountDHLExpressCreateRequestParameters'
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountDHLExpressCreateRequestParameters:
      properties:
        user_accepted_terms_and_conditions:
          description: >-
            Whether or not the user agrees to the DHL Express Terms and
            Conditions. If passed in as false, request will fail with error 400
          type: boolean
      required:
        - user_accepted_terms_and_conditions
      type: object
    CarrierAccountDpdDeCreateRequest:
      title: Shippo DPD DE account
      properties:
        carrier:
          example: dpd_de
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountDPDUKCreateRequest:
      title: Shippo DPD UK account
      properties:
        carrier:
          example: dpd_uk
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountFedExCreateRequest:
      title: Shippo FedEx account
      properties:
        carrier:
          example: fedex
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountHermesUKCreateRequest:
      title: Shippo Evri UK account
      properties:
        carrier:
          example: hermes_uk
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountMondialRelayCreateRequest:
      title: Shippo Mondial Relay account
      properties:
        carrier:
          example: mondialrelay
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountPosteItalianeCreateRequest:
      title: Shippo Poste Italiane account
      properties:
        carrier:
          example: poste_italiane
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountUPSCreateRequest:
      title: Shippo UPS account
      properties:
        carrier:
          example: ups
          type: string
        parameters:
          $ref: '#/components/schemas/CarrierAccountUPSCreateRequestParameters'
      required:
        - carrier
      type: object
    CarrierAccountUSPSCreateRequest:
      title: Shippo USPS account
      properties:
        carrier:
          example: usps
          type: string
        parameters:
          type: object
      required:
        - carrier
        - parameters
      type: object
    CarrierAccountUPSCreateRequestParameters:
      properties:
        billing_address_city:
          example: San Francisco
          type: string
        billing_address_country_iso2:
          example: US
          maxLength: 2
          minLength: 2
          type: string
        billing_address_state:
          example: CA
          maxLength: 2
          minLength: 2
          type: string
        billing_address_street1:
          example: 731 Market St
          type: string
        billing_address_street2:
          description: Empty string acceptable for billing_address_street2
          example: STE 200
          type: string
        billing_address_zip:
          example: '94103'
          maxLength: 5
          minLength: 5
          type: string
        company:
          description: >-
            Company name. Full name is acceptable in this field if the user has
            no company name
          example: Shippo
          type: string
        email:
          example: hippo@shippo.com
          type: string
        full_name:
          example: Shippo Meister
          type: string
        phone:
          description: Needs to be a valid phone number and cannot be null
          example: '1112223333'
          type: string
        pickup_address_city:
          description: User's pickup address city.
          example: San Francisco
          type: string
        pickup_address_country_iso2:
          description: User's pickup street 1.
          example: US
          maxLength: 2
          minLength: 2
          type: string
        pickup_address_same_as_billing_address:
          example: false
          type: boolean
        pickup_address_state:
          description: User's pickup address state.
          example: CA
          maxLength: 2
          minLength: 2
          type: string
        pickup_address_street1:
          description: User's pickup address street 1.
          example: 731 Market St
          type: string
        pickup_address_street2:
          description: User's pickup street 2.
          example: STE 200
          type: string
        pickup_address_zip:
          description: User's pickup address zip code.
          example: '94103'
          maxLength: 5
          minLength: 5
          type: string
        ups_agreements:
          description: >-
            Whether the user agrees to the UPS terms and conditions or not.
            Error 400 will be returned if passed in as false
          type: boolean
      required:
        - ups_agreements
        - billing_address_street1
        - billing_address_city
        - billing_address_zip
        - billing_address_state
        - billing_address_country_iso2
        - pickup_address_street1
        - pickup_address_city
        - pickup_address_zip
        - pickup_address_state
        - pickup_address_country_iso2
      type: object
    CarrierAccountUpdateRequest:
      allOf:
        - $ref: '#/components/schemas/CarrierAccountBase'
    DocumentUploadRequest:
      type: object
      required:
        - document_type
        - file
      properties:
        document_type:
          type: string
          description: Type of document to upload.
          enum:
            - LETTERHEAD
            - SIGNATURE
        file:
          type: string
          format: binary
          description: >-
            The document to upload. Only GIF and PNG image formats are
            supported. <br> `LETTERHEAD` files must be no larger than 700 pixels
            wide by 50 pixels high. <br> `SIGNATURE` files must be no larger
            than 240 pixels wide by 25 pixels high.
    Error:
      type: object
      required:
        - details
      properties:
        details:
          type: string
          description: Error details
    PaginatedList:
      properties:
        next:
          example: baseurl?page=3&results=10
          type: string
        previous:
          example: baseurl?page=1&results=10
          type: string
      type: object
    ConnectExistingOwnAccountRequest:
      title: Account parameters
      properties:
        account_id:
          example: '321123'
          type: string
        active:
          type: boolean
        carrier:
          example: fedex
          type: string
        metadata:
          example: FEDEX Account
          type: string
        parameters:
          oneOf:
            - $ref: '#/components/schemas/ConnectExistingOwnAccountParameters'
            - $ref: '#/components/schemas/UPSConnectExistingOwnAccountParameters'
            - $ref: '#/components/schemas/FedexConnectExistingOwnAccountParameters'
        test:
          example: false
          type: boolean
      required:
        - carrier
        - account_id
        - parameters
      type: object
    ConnectExistingOwnAccountParameters:
      title: Account parameters
      description: >
        An array of additional parameters for the account, such as e.g. password
        or token. Please check our <a
        href="https://docs.goshippo.com/docs/carriers/carrieraccounts/">carrier
        accounts guide</a> for the parameters per carrier.

        To protect account information, this field will be masked in any API
        response.
    FedexConnectExistingOwnAccountParameters:
      title: FedEx account parameters
      properties:
        use_multi_factor_registration:
          type: boolean
          enum:
            - true
          description: >-
            Must be true. FedEx accounts are registered using the multi-factor
            registration workflow.
        verification_option:
          type: string
          description: >-
            Determines the verification option to use for the account
            registration (Enum: SMS, EMAIL, CALL, INVOICE).
          enum:
            - EMAIL
            - SMS
            - INVOICE
            - CALL
        first_name:
          type: string
          description: First name of the account holder
        last_name:
          type: string
          description: Last name of the account holder
        phone_number:
          type: string
          description: Phone number of the account holder
        from_address_st:
          type: string
          description: >-
            Shipping address must match what you have on file with FedEx (see
            fedex.com profile)
        from_address_city:
          type: string
          description: City of the account holder
        from_address_state:
          type: string
          description: State of the account holder
        from_address_zip:
          type: string
          description: Zip code of the account holder
        from_address_country_iso2:
          type: string
          format: iso-3166-1-alpha-2
          description: Country of the account holder
        verification_pin:
          type: string
          description: >-
            The PIN to verify the account. Only use if `verification_option` is
            set to `SMS`, `EMAIL`, or `CALL`.
        verification_invoice_number:
          type: string
          description: >-
            The invoice number to verify the account. Only use if
            `verification_option` is set to `INVOICE`.
        verification_invoice_amount:
          type: string
          format: decimal
          example: 2345.67
          description: >-
            The invoice amount to verify the account. Only use if
            `verification_option` is set to `INVOICE`.
        verification_invoice_date:
          type: string
          format: date
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2024-01-01'
          description: >-
            The invoice date to verify the account. (YYYY-MM-DD). Only use if
            `verification_option` is set to `INVOICE`.
        verification_invoice_currency:
          type: string
          format: iso-4217
          example: USD
          description: >-
            The invoice currency to verify the account. Only use if
            `verification_option` is set to `INVOICE`.
      required:
        - use_multi_factor_registration
        - verification_option
        - first_name
        - last_name
        - phone_number
        - from_address_st
        - from_address_city
        - from_address_state
        - from_address_zip
        - from_address_country_iso2
      type: object
    FedexConnectExistingOwnAccountParametersResponse:
      title: FedEx account parameters
      allOf:
        - $ref: '#/components/schemas/FedexConnectExistingOwnAccountParameters'
        - type: object
          properties:
            verification_status:
              type: string
              description: The status of the verification
              enum:
                - PENDING
                - COMPLETE
                - FAILED
            use_rest_api:
              type: boolean
              description: Determines if the account is a REST API account or not
            child_key:
              type: string
              description: The API key of the account
            child_secret:
              type: string
              description: The API secret of the account
            letterhead_reference_id:
              type: string
              description: The letterhead reference id of the account
            signature_reference_id:
              type: string
              description: The signature reference id of the account
    UPSConnectExistingOwnAccountParameters:
      title: UPS account parameters
      description: >-
        An array of additional parameters for the account, such as e.g. password
        or token.

        Please check the <a
        href="https://docs.goshippo.com/docs/carriers/carrieraccounts/">carrier
        accounts tutorial</a> page for the parameters per carrier.<br> 

        To protect account information, this field will be masked in any API
        response.
      properties:
        account_number:
          description: The UPS account number
          example: 94567e
          type: string
        aia_country_iso2:
          description: >-
            Only required if has_invoice is true. Country associated with the
            account that issued the invoice
          example: US
          type: string
        billing_address_city:
          example: San Francisco
          type: string
        billing_address_country_iso2:
          example: US
          maxLength: 2
          minLength: 2
          type: string
        billing_address_state:
          example: CA
          maxLength: 2
          minLength: 2
          type: string
        billing_address_street1:
          example: 731 Market St
          type: string
        billing_address_street2:
          description: Empty string acceptable for billing_address_street2
          example: STE 200
          type: string
        billing_address_zip:
          example: '94103'
          maxLength: 5
          minLength: 5
          type: string
        collec_country_iso2:
          example: US
          maxLength: 2
          minLength: 2
          type: string
        collec_zip:
          description: Zip code of the collection/pickup address
          example: '94103'
          maxLength: 5
          minLength: 5
          type: string
        company:
          description: >-
            Company name. Full name is acceptable in this field if the user has
            no company name
          example: Shippo
          type: string
        currency_code:
          description: >-
            Only required if has_invoice is true. 3-letter currency code
            associated with invoice_value
          example: USD
          maxLength: 3
          minLength: 3
          type: string
        email:
          example: hippo@shippo.com
          type: string
        full_name:
          example: Shippo Meister
          type: string
        has_invoice:
          description: >-
            true if user has been issued a UPS invoice within the past 90 days
            for the US or Canada; and 45 days for any other countries. User can
            use data from any of the last 3 invoices
          type: boolean
        invoice_controlid:
          description: Only required if aia_country_iso2 is US and has_invoice is true.
          example: '1234'
          maxLength: 4
          minLength: 4
          type: string
        invoice_date:
          description: >-
            Only required if has_invoice is true. Date the invoice was issued.
            yyyymmdd format
          example: '20210529'
          type: string
        invoice_number:
          example: '1112234'
          maxLength: 15
          minLength: 1
          type: string
        invoice_value:
          description: >-
            Only required if has_invoice is true. Max 16 digits before decimal
            and 2 digits after decimal
          example: '11.23'
          type: string
        phone:
          example: '1112223333'
          type: string
        title:
          description: >-
            User's title, e.g. including but not limited to Manager, Doctor,
            Artist, Engineer, Mr, Ms, Mrs, Mx
          example: Manager
          type: string
        ups_agreements:
          description: >-
            Whether the user agrees to the UPS terms and conditions or not.
            Error 400 will be returned if passed in as false
          type: boolean
      required:
        - ups_agreements
        - account_number
        - title
        - company
        - full_name
        - phone
        - billing_address_street1
        - billing_address_city
        - billing_address_zip
        - billing_address_state
        - billing_address_country_iso2
        - collec_zip
        - collec_country_iso2
        - has_invoice
        - email
      type: object
    CarriersEnum:
      type: string
      enum:
        - airterra
        - apc_postal
        - apg
        - aramex
        - asendia_us
        - australia_post
        - axlehire
        - better_trucks
        - borderguru
        - boxberry
        - bring
        - canada_post
        - cdl
        - chronopost
        - collect_plus
        - correios_br
        - correos_espana
        - colissimo
        - deutsche_post
        - dhl_benelux
        - dhl_ecommerce
        - dhl_express
        - dhl_germany_c2c
        - dhl_germany
        - dpd_de
        - dpd_uk
        - estafeta
        - fastway_australia
        - fedex
        - globegistics
        - gls_us
        - gophr
        - gso
        - hermes_germany_b2c
        - hermes_uk
        - hongkong_post
        - lasership
        - lso
        - mondial_relay
        - new_zealand_post
        - nippon_express
        - ontrac
        - parcelforce
        - passport
        - pcf
        - poste_italiane
        - posti
        - purolator
        - royal_mail
        - rr_donnelley
        - russian_post
        - skypostal
        - stuart
        - swyft
        - uds
        - ups
        - usps
        - veho
      description: >
        |Token | Carrier name|

        |:---|:---|

        | airterra | Airterra |

        | apc_postal | APC Postal|

        | apg | APG|

        | aramex | Aramex|

        | asendia_us | Asendia US|

        | australia_post | Australia Post (also used for Startrack)|

        | axlehire | Axlehire|

        | better_trucks | BetterTrucks|

        | borderguru | BorderGuru|

        | boxberry | Boxberry|

        | bring | Bring (also used for Posten Norge)|

        | canada_post | Canada Post|

        | cdl | CDL|

        | chronopost | Chronopost|

        | collect_plus | CollectPlus|

        | correios_br | CorreiosBR|

        | correos_espana | Correos España |

        | colissimo | Colissimo|

        | deutsche_post | Deutsche Post|

        | dhl_benelux | DHL Benelux|

        | dhl_ecommerce | DHL eCommerce|

        | dhl_express | DHL Express|

        | dhl_germany_c2c | DHL Germany C2C|

        | dhl_germany | DHL Germany|

        | dpd_de | DPD GERMANY|

        | dpd_uk | DPD UK|

        | estafeta | Estafeta|

        | fastway_australia | Aramex|

        | fedex | FedEx|

        | globegistics | Globegistics (now Asendia)|

        | gls_us | GLS US|

        | gophr | Gophr|

        | gso | GSO|

        | hermes_germany_b2c | Hermes Germany B2C|

        | hermes_uk | Evri UK |

        | hongkong_post | Hongkong Post|

        | lasership | LaserShip|

        | lso | LSO|

        | mondial_relay | Mondial Relay|

        | new_zealand_post | New Zealand Post (also used for Pace and
        CourierPost)|

        | nippon_express | Nippon Express|

        | ontrac | OnTrac|

        | parcelforce | Parcelforce|

        | passport | Passport|

        | pcf | PCF|

        | poste_italiane | Poste Italiane |

        | posti | Posti|

        | purolator | Purolator|

        | royal_mail | Royal Mail|

        | rr_donnelley | ePost Global|

        | russian_post | Russian Post|

        | skypostal | SkyPostal|

        | stuart | Stuart|

        | swyft | Swyft|

        | uds | UDS (United Delivery Service)|

        | ups | UPS|

        | usps | USPS|

        | veho | Veho |
