openapi: 3.1.0
info:
  description: Shippo Shipping Surcharge report API
  title: Shippo Shipping Surcharge Report API
  version: 0.1.0
servers:
  - url: https://api.goshippo.com
tags:
  - name: Surcharges
    description: Retrieve shipping surcharge reports
paths:
  /v2/reports/surcharges:
    get:
      tags:
        - Surcharges
      description: >-
        Returns a list of surcharge files. The returned list is arranged by date
        created, in descending order. Use `page` and `limit` to refine your
        list.
      operationId: get_all_files_v2_reports_surcharges_get
      parameters:
        - description: Link to the next page
          in: query
          name: page
          required: false
          schema:
            description: Link to the next page
            examples:
              - RSVMTQTVFX
            title: Page
            type: string
        - description: The upper limit to the number of resources returned
          in: query
          name: limit
          required: false
          schema:
            description: The upper limit to the number of resources returned
            title: Limit
            type: integer
            minimum: 1
            default: 10
      x-codeSamples:
        - lang: cURL
          label: curl
          source: >-
            curl -i -X GET \

            'https://api.goshippo.com/v2/reports/surcharges?page=RSVMTQTVFX&limit=10'
            \

            -H 'Authorization: ShippoToken <API_TOKEN>'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - query
                      - id
                    msg: Not valid string for page
                    type: string_type
                    url: https://errors.pydantic.dev/2.3/v/string_type
                  - loc:
                      - query
                      - id
                    msg: Not valid int for limit
                    type: int_parsing
                    url: https://errors.pydantic.dev/2.3/v/int_parsing
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
      security:
        - Shippo_Token: []
      summary: List surcharge files
  /v2/reports/surcharges/{file_id}:
    x-ignoredHeaderParameters:
      - Authorization
    get:
      tags:
        - Surcharges
      description: >-
        Returns a redirect URL to download the surcharge file content. <br><br> 

        A successful response returns a 302 status code. Your client should
        automatically follow the redirected link to download the file.

        <br> 

        Some clients, such as Swagger UI, can include the `authorization` header
        when following the redirected link. This will cause the request to fail
        with a 400 Bad Request response.

        To avoid this issue, ensure that the `authorization` header is removed
        when the client follows the redirected URL.
      operationId: get_file_v2_reports_surcharges__file_id__get
      x-hideTryItPanel: true
      parameters:
        - in: path
          name: file_id
          required: true
          schema:
            format: uuid
            title: File Id
            type: string
      x-codeSamples:
        - lang: cURL
          label: curl
          source: >-
            curl -i -X GET \

            'https://api.goshippo.com/v2/reports/surcharges/4e43e2df-3e35-4985-b718-2d21e5078175'
            \

            -H 'Authorization: ShippoToken <API_TOKEN>'
      responses:
        '302':
          description: 'Successful Response: Redirect to download file'
          headers:
            Location:
              description: >-
                An URI to perform a HTTP GET to download the file content. It is
                RFC-7231 compliant
                https://datatracker.ietf.org/doc/html/rfc7231#section-6.4.3
              examples:
                signed_url:
                  description: Redirect URI to download the file.
                  value: https://s3.amazonaws.com/your-bucket/your-file
              schema:
                format: uri
                type: string
          x-redocly:
            strip_headers:
              - Authorization
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '422':
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - query
                      - id
                    msg: Not valid file_id UUID
                    type: uuid_type
                    url: https://errors.pydantic.dev/2.3/v/uuid_type
                  - loc:
                      - query
                      - id
                    msg: Could not parse file_id UUID
                    type: uuid_parsing
                    url: https://errors.pydantic.dev/2.3/v/uuid_parsing
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
      security:
        - Shippo_Token: []
      summary: Retrieve surcharge file
components:
  schemas:
    ErrorDetail:
      properties:
        input:
          anyOf:
            - {}
            - type: 'null'
          description: The input values for this field
          examples:
            - 'null'
          title: Input
        loc:
          description: The location of the error
          examples:
            - - query
              - country_code
          items:
            type: string
          title: Loc
          type: array
        msg:
          description: The error message
          examples:
            - Field required
          title: Msg
          type: string
        type:
          description: The type of error
          examples:
            - missing
          title: Type
          type: string
      required:
        - type
        - loc
        - msg
      title: ErrorDetail
      type: object
    FileListResponse:
      description: Response contains a list of file details and pagination information
      properties:
        page_info:
          $ref: '#/components/schemas/PageInfo'
        resources:
          default: []
          items:
            $ref: '#/components/schemas/FileMetaData'
          title: Resources
          type: array
      required:
        - page_info
      title: FileListResponse
      type: object
    FileMetaData:
      description: >-
        The response contains file_id (which can be used for next requests) and
        the date the file was processed
      properties:
        date:
          description: Date the file was processed
          examples:
            - '2021-09-01T00:00:00Z'
          format: date-time
          title: Date
          type: string
        file_id:
          description: File ID
          examples:
            - 4e43e2df-3e35-4985-b718-2d21e5078175
          format: uuid
          title: File Id
          type: string
      required:
        - file_id
        - date
      title: FileMetaData
      type: object
    NotFoundResponse:
      properties:
        detail:
          default: File not Found
          examples:
            - File not Found
          title: Detail
          type: string
      title: NotFoundResponse
      type: object
    PageInfo:
      description: Link to the next page and previous page
      properties:
        next:
          anyOf:
            - type: string
            - type: 'null'
          description: Link to the next page
          examples:
            - RSVMTQTVFX
          title: Next
        prev:
          anyOf:
            - type: string
            - type: 'null'
          description: Link to the previous page
          examples:
            - DMHFVDVQRZ
          title: Prev
      title: PageInfo
      type: object
    UnprocessableEntityResponse:
      description: A response for invalid requests with details of the issue.
      properties:
        detail:
          description: Details of the issue with the request.
          items:
            $ref: '#/components/schemas/ErrorDetail'
          title: Detail
          type: array
      required:
        - detail
      title: UnprocessableEntityResponse
      type: object
  securitySchemes:
    Shippo_Token:
      description: |

        Enter your shippo token with the ShippoToken prefix.
        <br></br>
        Example: `ShippoToken shippo_live_xxxx`
      in: header
      name: Authorization
      type: apiKey
