openapi: 3.0.0 info: title: Reports API version: v2 description: API for accessing Shippo billing reports and invoice data. x-logo: url: https://docs.goshippo.com/images/shippo-logo.svg servers: - url: https://api.goshippo.com security: - APIKeyHeader: [] tags: - name: Reports description: |- Use the Reports API to retrieve reports that have been scheduled or requested on demand. At the moment, only scheduled reports are supported. 1. Use `/v2/reports/{report_type_uuid}/runs` to list the available reports. 2. Use `/v2/reports/{report_type_uuid}/runs/{report_run_uuid}/download` to download the csv file of a report instance. paths: /v2/reports/{report_type_uuid}/runs: get: tags: - Reports summary: Return list of reports operationId: list_report_runs description: | Returns a list of reports that can be downloaded. A report type is a report that can be executed on a schedule and/or on demand. If you have requested Shippo a custom report, you will receive the report type UUID that represents that report type. With this report type UUID, you can call this endpoint to list all the available runs of your report. parameters: - name: report_type_uuid in: path schema: type: string format: uuid title: Report Type UUID required: true description: UUID of the report type - name: status in: query required: false schema: $ref: '#/components/schemas/ReportStatus' description: Filters report runs by their current status. This is an optional parameter, but it's recommended setting it to SUCCEEDED if your integration doesn't handle the other statuses - name: mode in: query schema: $ref: '#/components/schemas/ReportInstanceMode' required: false description: Filters results for only one report mode. (only scheduled reports are supported currently) - name: page in: query required: false schema: type: string description: Link to the next page example: bmV4dDs5MTsyMDI0LTA4LTA3VDE0OjQ1OjA4LjkyNzg1MSswMDowMA== title: Page - name: limit in: query required: false schema: type: integer minimum: 1 description: The upper limit to the number of resources returned default: 10 title: Limit description: The upper limit to the number of results returned x-codeSamples: - lang: cURL label: cURL source: |- curl -i -X GET \ 'https://api.goshippo.com/v2/reports/{report_type_uuid}/runs?status=QUEUED&mode=ON_DEMAND&page=bmV4dDs5MTsyMDI0LTA4LTA3VDE0OjQ1OjA4LjkyNzg1MSswMDowMA==&limit=10' \ -H 'Authorization: ShippoToken ' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListReportRunResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v2/reports/{report_type_uuid}/runs/{report_run_uuid}/download: get: summary: Download report description: |- Returns a redirect URL to download the report file. After processing the response from `/runs` endpoint, use the same `report_type_uuid` and the object_id of the report you want to retrieve. A successful response returns a 302 status code. Your client should automatically follow the redirected link to download the file. 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_report_run_download_url tags: - Reports parameters: - name: report_type_uuid in: path required: true schema: type: string format: uuid title: Report Type Uuid description: UUID of the report type - name: report_run_uuid in: path required: true schema: type: string format: uuid title: Report Run UUID description: UUID of the report instance (object_id returned by /runs) x-codeSamples: - lang: cURL label: cURL source: |- curl -i -X GET \ 'https://api.goshippo.com/v2/reports/{report_type_uuid}/runs/{report_run_uuid}/download' \ -H 'Authorization: ShippoToken ' responses: '302': description: Redirect to download URL headers: Location: schema: type: string format: uri 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 example: "https://s3.amazonaws.com/your-bucket/your-file" '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: ReportStatus: type: string enum: - QUEUED - PROCESSING - SUCCEEDED - FAILED title: ReportStatus ReportInstanceMode: type: string enum: - ON_DEMAND - SCHEDULED title: ReportInstanceMode ListReportRunResponse: properties: resources: items: $ref: '#/components/schemas/ReportRunResponse' type: array title: Resources page_info: allOf: - $ref: '#/components/schemas/PageInfo' type: object title: ListReportRunResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ReportRunResponse: properties: object_id: type: string format: uuid title: Object Id example: 079aa9eb-9c0c-484a-b4fb-6507b43cf722 created_at: type: string format: date-time title: Created At example: '2021-09-01T00:00:00.000000Z' mode: allOf: - $ref: '#/components/schemas/ReportInstanceMode' example: ON_DEMAND status: allOf: - $ref: '#/components/schemas/ReportStatus' example: SUCCEEDED type: object required: - object_id - created_at - mode - status title: ReportRunResponse PageInfo: properties: next: type: string title: Next description: Link to the next page example: bmV4dDs5MTsyMDI0LTA4LTA3VDE0OjQ1OjA4LjkyNzg1MSswMDowMA== prev: type: string title: Prev description: Link to the previous page example: cHJldjs5MjsyMDI0LTA5LTA1VDEzOjQwOjE1Ljk2NjY1NCswMDowMA== type: object title: PageInfo description: Link to the next page and previous page ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: APIKeyHeader: in: header name: Authorization type: apiKey x-default: "ShippoToken "