openapi: 3.1.0
info:
  title: Reporting API
  version: 0.1.0
servers:
- url: https://api.goshippo.com
paths:
  /v2/reporting/runs:
    post:
      tags:
      - Report Runs
      summary: Create Report Run
      operationId: create_report_run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReportRunRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AcceptedReportRunResponse'
                - $ref: '#/components/schemas/RunningReportRunResponse'
                - $ref: '#/components/schemas/SucceededReportRunResponse'
                - $ref: '#/components/schemas/FailedReportRunResponse'
                discriminator:
                  propertyName: status
                  mapping:
                    QUEUED: '#/components/schemas/AcceptedReportRunResponse'
                    PROCESSING: '#/components/schemas/RunningReportRunResponse'
                    SUCCEEDED: '#/components/schemas/SucceededReportRunResponse'
                    FAILED: '#/components/schemas/FailedReportRunResponse'
                title: Response Create Report Run V2 Reporting Api Runs Post
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                required:
                - detail
              example:
                detail: Authentication credentials were not provided.
        '422':
          description: Validation error
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              example:
                type: https://reporthub.shippo.com/errors/validation-error
                title: Validation Error
                status: 422
                detail: The request is invalid.
        '200':
          description: Idempotent replay of an existing report run.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AcceptedReportRunResponse'
                - $ref: '#/components/schemas/RunningReportRunResponse'
                - $ref: '#/components/schemas/SucceededReportRunResponse'
                - $ref: '#/components/schemas/FailedReportRunResponse'
                discriminator:
                  propertyName: status
                  mapping:
                    QUEUED: '#/components/schemas/AcceptedReportRunResponse'
                    PROCESSING: '#/components/schemas/RunningReportRunResponse'
                    SUCCEEDED: '#/components/schemas/SucceededReportRunResponse'
                    FAILED: '#/components/schemas/FailedReportRunResponse'
                title: Response 200 Create Report Run V2 Reporting Api Runs Post
        '400':
          description: Invalid run request
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              examples:
                invalid_column:
                  value:
                    type: https://reporthub.shippo.com/errors/invalid-column
                    title: Invalid Request
                    status: 400
                    detail: One or more requested columns are invalid.
                invalid_parameter:
                  value:
                    type: https://reporthub.shippo.com/errors/invalid-parameter
                    title: Invalid Request
                    status: 400
                    detail: The run request is invalid. Check the requested report,
                      interval, and columns.
        '404':
          description: Report type or data unavailable
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              examples:
                report_type_not_found:
                  value:
                    type: https://reporthub.shippo.com/errors/report-type-not-found
                    title: Report Type Not Found
                    status: 404
                    detail: The requested report type was not found.
                data_unavailable:
                  value:
                    type: https://reporthub.shippo.com/errors/data-unavailable
                    title: Data Unavailable
                    status: 404
                    detail: Data is not available for the requested interval.
        '409':
          description: Idempotency conflict
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              example:
                type: https://reporthub.shippo.com/errors/idempotency-conflict
                title: Idempotency Conflict
                status: 409
                detail: The same idempotency key is already bound to a different request payload
        '503':
          description: Service unavailable
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              example:
                type: https://reporthub.shippo.com/errors/service-unavailable
                title: Service Unavailable
                status: 503
                detail: The service is temporarily unavailable.
      security:
      - ShippoTokenAuth: []
    get:
      tags:
      - Report Runs
      summary: List Report Runs
      operationId: list_report_runs
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          description: Maximum recent runs to return.
          default: 50
          title: Limit
        description: Maximum recent runs to return.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRunListResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                required:
                - detail
              example:
                detail: Authentication credentials were not provided.
        '422':
          description: Validation error
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              example:
                type: https://reporthub.shippo.com/errors/validation-error
                title: Validation Error
                status: 422
                detail: The request is invalid.
      security:
      - ShippoTokenAuth: []
  /v2/reporting/runs/{run_id}:
    get:
      tags:
      - Report Runs
      summary: Get Report Run
      operationId: get_report_run
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AcceptedReportRunResponse'
                - $ref: '#/components/schemas/RunningReportRunResponse'
                - $ref: '#/components/schemas/SucceededReportRunResponse'
                - $ref: '#/components/schemas/FailedReportRunResponse'
                discriminator:
                  propertyName: status
                  mapping:
                    QUEUED: '#/components/schemas/AcceptedReportRunResponse'
                    PROCESSING: '#/components/schemas/RunningReportRunResponse'
                    SUCCEEDED: '#/components/schemas/SucceededReportRunResponse'
                    FAILED: '#/components/schemas/FailedReportRunResponse'
                title: Response Get Report Run V2 Reporting Api Runs  Run Id  Get
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                required:
                - detail
              example:
                detail: Authentication credentials were not provided.
        '422':
          description: Validation error
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              example:
                type: https://reporthub.shippo.com/errors/validation-error
                title: Validation Error
                status: 422
                detail: The request is invalid.
        '404':
          description: Run not found
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              example:
                type: https://reporthub.shippo.com/errors/run-not-found
                title: Run Not Found
                status: 404
                detail: The requested run was not found.
      security:
      - ShippoTokenAuth: []
  /v2/reporting/reports:
    get:
      tags:
      - Reports
      summary: List Report Types
      operationId: list_report_types
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportTypeListResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                required:
                - detail
              example:
                detail: Authentication credentials were not provided.
      security:
      - ShippoTokenAuth: []
  /v2/reporting/reports/{report_type}:
    get:
      tags:
      - Reports
      summary: Get Report Type
      operationId: get_report_type
      parameters:
      - name: report_type
        in: path
        required: true
        schema:
          type: string
          title: Report Type
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportTypeResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                required:
                - detail
              example:
                detail: Authentication credentials were not provided.
        '404':
          description: Report type not found
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              example:
                type: https://reporthub.shippo.com/errors/report-type-not-found
                title: Report Type Not Found
                status: 404
                detail: The requested report type was not found.
        '422':
          description: Validation error
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              example:
                type: https://reporthub.shippo.com/errors/validation-error
                title: Validation Error
                status: 422
                detail: The request is invalid.
      security:
      - ShippoTokenAuth: []
components:
  schemas:
    AcceptedReportRunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        report_type:
          type: string
          title: Report Type
        interval:
          $ref: '#/components/schemas/ReportRunInterval'
        columns:
          items:
            type: string
          type: array
          title: Columns
        output_format:
          $ref: '#/components/schemas/OutputFormat'
        created:
          type: integer
          title: Created
        status:
          type: string
          const: QUEUED
          title: Status
      type: object
      required:
      - id
      - report_type
      - interval
      - columns
      - output_format
      - created
      - status
      title: AcceptedReportRunResponse
      description: Run resource while queued for processing.
    CreateReportRunInterval:
      properties:
        start:
          type: integer
          minimum: 0.0
          title: Start
          example: 1704067200
        end:
          type: integer
          minimum: 0.0
          title: End
          example: 1706745600
      additionalProperties: false
      type: object
      required:
      - start
      - end
      title: CreateReportRunInterval
      description: Requested report interval in UTC epoch seconds.
    CreateReportRunRequest:
      properties:
        report_type:
          type: string
          title: Report Type
        interval:
          $ref: '#/components/schemas/CreateReportRunInterval'
        columns:
          anyOf:
          - items:
              type: string
            type: array
            minItems: 1
          - type: 'null'
          title: Columns
        output_format:
          $ref: '#/components/schemas/OutputFormat'
          default: csv_gzip
        idempotency_key:
          anyOf:
          - type: string
            maxLength: 128
            minLength: 1
          - type: 'null'
          title: Idempotency Key
          description: Optional client key that makes create idempotent. Reusing
            the same key with the same request returns the original run (200);
            reusing it with a different request returns 409.
      additionalProperties: false
      type: object
      required:
      - report_type
      - interval
      title: CreateReportRunRequest
      description: Create an asynchronous report run. Select column names from
        the report type's available_columns.
    FailedReportRunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        report_type:
          type: string
          title: Report Type
        interval:
          $ref: '#/components/schemas/ReportRunInterval'
        columns:
          items:
            type: string
          type: array
          title: Columns
        output_format:
          $ref: '#/components/schemas/OutputFormat'
        created:
          type: integer
          title: Created
        status:
          type: string
          const: FAILED
          title: Status
        completed:
          type: integer
          title: Completed
        error:
          $ref: '#/components/schemas/ReportRunError'
      type: object
      required:
      - id
      - report_type
      - interval
      - columns
      - output_format
      - created
      - status
      - completed
      - error
      title: FailedReportRunResponse
      description: Terminal run resource after an unsuccessful run.
    OutputFormat:
      type: string
      enum:
      - csv
      - csv_gzip
      - parquet
      title: OutputFormat
      description: File format for the generated report.
    PendingDataAvailabilityResponse:
      properties:
        status:
          type: string
          const: pending
          title: Status
      type: object
      required:
      - status
      title: PendingDataAvailabilityResponse
      description: Data availability state while bounds are still being computed.
    PublicReportColumnResponse:
      properties:
        name:
          type: string
          title: Name
        display_name:
          type: string
          title: Display Name
        is_default:
          type: boolean
          title: Is Default
      type: object
      required:
      - name
      - display_name
      - is_default
      title: PublicReportColumnResponse
      description: Column metadata returned by report type discovery.
    PublicRunErrorCode:
      type: string
      enum:
      - invalid_run_request
      - run_failed
      - run_processing_failed
      - run_timeout
      - service_unavailable
      title: PublicRunErrorCode
      description: Stable error codes for failed report runs.
    ReadyDataAvailabilityResponse:
      properties:
        status:
          type: string
          const: ready
          title: Status
        start:
          type: integer
          title: Start
          example: 1704067200
        end:
          type: integer
          title: End
          example: 1706745600
        updated:
          type: integer
          title: Updated
      type: object
      required:
      - status
      - start
      - end
      - updated
      title: ReadyDataAvailabilityResponse
      description: Available data bounds and the time they were last checked.
    ReportRunDownloadAvailable:
      properties:
        status:
          type: string
          const: available
          title: Status
        url:
          type: string
          title: Url
          description: A time-limited signed download URL for the generated report file.
        expires:
          type: integer
          title: Expires
          description: UTC epoch second after which the download URL expires.
      type: object
      required:
      - status
      - url
      - expires
      title: ReportRunDownloadAvailable
      description: Download state when a URL is available for the completed report.
    ReportRunDownloadUnavailable:
      properties:
        status:
          type: string
          const: unavailable
          title: Status
      type: object
      required:
      - status
      title: ReportRunDownloadUnavailable
      description: Download state when a report file is not available.
    ReportRunError:
      properties:
        code:
          $ref: '#/components/schemas/PublicRunErrorCode'
        message:
          type: string
          title: Message
      type: object
      required:
      - code
      - message
      title: ReportRunError
      description: Error details for an unsuccessful report run.
    ReportRunInterval:
      properties:
        start:
          type: integer
          title: Start
          example: 1704067200
        end:
          type: integer
          title: End
          example: 1706745600
      type: object
      required:
      - start
      - end
      title: ReportRunInterval
      description: Report interval in UTC epoch seconds.
    ReportRunListResponse:
      properties:
        items:
          items:
            oneOf:
            - $ref: '#/components/schemas/AcceptedReportRunResponse'
            - $ref: '#/components/schemas/RunningReportRunResponse'
            - $ref: '#/components/schemas/SucceededReportRunResponse'
            - $ref: '#/components/schemas/FailedReportRunResponse'
            discriminator:
              propertyName: status
              mapping:
                QUEUED: '#/components/schemas/AcceptedReportRunResponse'
                FAILED: '#/components/schemas/FailedReportRunResponse'
                PROCESSING: '#/components/schemas/RunningReportRunResponse'
                SUCCEEDED: '#/components/schemas/SucceededReportRunResponse'
          type: array
          title: Items
      type: object
      required:
      - items
      title: ReportRunListResponse
      description: List of report runs.
    ReportRunResult:
      properties:
        row_count:
          type: integer
          title: Row Count
        size_bytes:
          type: integer
          title: Size Bytes
        download:
          oneOf:
          - $ref: '#/components/schemas/ReportRunDownloadAvailable'
          - $ref: '#/components/schemas/ReportRunDownloadUnavailable'
          title: Download
          discriminator:
            propertyName: status
            mapping:
              available: '#/components/schemas/ReportRunDownloadAvailable'
              unavailable: '#/components/schemas/ReportRunDownloadUnavailable'
      type: object
      required:
      - row_count
      - size_bytes
      - download
      title: ReportRunResult
      description: Successful run result and download state.
    ReportTypeListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ReportTypeResponse'
          type: array
          title: Items
      type: object
      required:
      - items
      title: ReportTypeListResponse
      description: List of available report types.
    ReportTypeResponse:
      properties:
        report_type:
          type: string
          title: Report Type
        name:
          type: string
          title: Name
        category:
          type: string
          title: Category
        description:
          type: string
          title: Description
        available_columns:
          items:
            $ref: '#/components/schemas/PublicReportColumnResponse'
          type: array
          title: Available Columns
        data_availability:
          oneOf:
          - $ref: '#/components/schemas/PendingDataAvailabilityResponse'
          - $ref: '#/components/schemas/ReadyDataAvailabilityResponse'
          title: Data Availability
          discriminator:
            propertyName: status
            mapping:
              pending: '#/components/schemas/PendingDataAvailabilityResponse'
              ready: '#/components/schemas/ReadyDataAvailabilityResponse'
      type: object
      required:
      - report_type
      - name
      - category
      - description
      - available_columns
      - data_availability
      title: ReportTypeResponse
      description: 'Report type metadata returned by the Reporting API.


        The version is embedded in the ``report_type`` key (for example

        ``invoice.v1``) and discovery only returns active types, so neither fact is

        repeated as a separate field.'
    RunningReportRunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        report_type:
          type: string
          title: Report Type
        interval:
          $ref: '#/components/schemas/ReportRunInterval'
        columns:
          items:
            type: string
          type: array
          title: Columns
        output_format:
          $ref: '#/components/schemas/OutputFormat'
        created:
          type: integer
          title: Created
        status:
          type: string
          const: PROCESSING
          title: Status
      type: object
      required:
      - id
      - report_type
      - interval
      - columns
      - output_format
      - created
      - status
      title: RunningReportRunResponse
      description: Run resource while processing is in progress.
    SucceededReportRunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        report_type:
          type: string
          title: Report Type
        interval:
          $ref: '#/components/schemas/ReportRunInterval'
        columns:
          items:
            type: string
          type: array
          title: Columns
        output_format:
          $ref: '#/components/schemas/OutputFormat'
        created:
          type: integer
          title: Created
        status:
          type: string
          const: SUCCEEDED
          title: Status
        completed:
          type: integer
          title: Completed
        result:
          $ref: '#/components/schemas/ReportRunResult'
      type: object
      required:
      - id
      - report_type
      - interval
      - columns
      - output_format
      - created
      - status
      - completed
      - result
      title: SucceededReportRunResponse
      description: Terminal run resource after successful completion.
  securitySchemes:
    ShippoTokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Shippo API token header, for example `ShippoToken shippo_live_xxxx`.