Sendcloud Reporting API v2
Legacy v2 Reporting surface for shipment-level billing line items.
OpenAPI Specification
openapi: 3.1.0
info:
title: Reporting
version: 2.0.0
description: >-
The Reporting API allows you to generate and download a CSV report
containing data related to your Sendcloud account for tracking and analysis
purposes.
contact:
name: Sendcloud API Support
url: https://www.sendcloud.dev
email: [email protected]
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://panel.sendcloud.sc/api/v2
description: Sendcloud Production
tags:
- name: Reporting
description: Generate data exports and reports.
paths:
/reporting/parcels:
post:
tags:
- Reporting
summary: Create a parcels report
x-mint:
href: /api/v2/reporting/create-a-parcels-report
content: >-
The parcels included in the report will depend on the `filters`
provided, and the columns will be determined by the `fields`
parameter.
Use this endpoint to create the report and obtain the report `id`,
which you will use to obtain the actual CSV download via the [Retrieve
a parcels report](/api/v2/reporting/retrieve-a-parcels-report)
endpoint.
description: >-
Generate a CSV report containing information about outgoing or incoming
parcels.
operationId: sc-public-v2-reporting_analytics-post-parcels_report
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelsReportRequest'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelsReport'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPError'
examples:
ValidationError:
summary: Validation Error
value:
detail:
- loc:
- body
- fields
msg: >-
value is not a valid enumeration member; permitted:
'parcel_id', 'direction', 'carrier_code',
'carrier_name', 'from_company_name', 'contract_id',
'contract_type', 'origin_city', 'origin_postal_code',
'origin_country_code', 'origin_country_name',
'destination_city', 'destination_postal_code',
'destination_country_code',
'destination_country_name', 'order_number',
'tracking_number', 'created_at', 'updated_at',
'announced_at', 'shipped_at', 'first_delivery_at',
'arrived_at', 'shipping_method',
'shipping_method_name', 'price', 'global_status_slug',
'carrier_status', 'integration_id',
'integration_type', 'weight'
type: type_error.enum
ctx:
enum_values:
- parcel_id
- direction
- carrier_code
- carrier_name
- from_company_name
- contract_id
- contract_type
- origin_city
- origin_postal_code
- origin_country_code
- origin_country_name
- destination_city
- destination_postal_code
- destination_country_code
- destination_country_name
- order_number
- tracking_number
- created_at
- updated_at
- announced_at
- shipped_at
- first_delivery_at
- arrived_at
- shipping_method
- shipping_method_name
- price
- global_status_slug
- carrier_status
- integration_id
- integration_type
- weight
/reporting/parcels/{report_id}:
get:
tags:
- Reporting
summary: Retrieve a parcels report
x-mint:
href: /api/v2/reporting/retrieve-a-parcels-report
content: >-
The report `id` is the one you obtained via the [Create a parcels
report](/api/v2/reporting/create-a-parcels-report) endpoint.
Depending on the size of the report, it may not be immediately
available for download. The status of the report is indicated in the
response body under the `status_message` field.
The report will expire after a certain amount of time, after which you
will have to generate it again. The time of expiry is indicated in the
response body under the `expires_at` field.
description: Generate a URL to download a parcels report in CSV format.
operationId: sc-public-v2-reporting_analytics-get-parcels_report
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
parameters:
- required: true
schema:
title: Report Id
type: string
format: uuid
name: report_id
in: path
description: Report id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelsReport'
'422':
$ref: '#/components/responses/422'
parameters:
- schema:
type: integer
name: report_id
in: path
required: true
description: The report unique identifier
components:
schemas:
HTTPError:
title: HTTP Error Object
type: object
properties:
detail:
title: Detail
type: array
items:
$ref: '#/components/schemas/Error'
ParcelDirections:
type: string
title: Parcel Directions
enum:
- incoming
- outgoing
description: The direction of the parcel
example: outgoing
ParcelsReport:
title: Parcels Report Object
type: object
description: |-
Report information
This model contains information about the creation of a report and the
status of processing such report.
properties:
id:
type: string
title: Id
description: The unique identifier for the report.
format: uuid
example: 419f3be0-2f49-434b-bee4-d8cff9cf7d01
user_id:
type: integer
title: User Id
description: Id of the user that created the report.
minimum: 1
example: 1
status:
allOf:
- $ref: '#/components/schemas/ReportStatus'
description: Current status of the report.
example: ready
status_message:
title: Status Message
type: string
description: Description of the status of the report.
example: The report is ready
filters:
$ref: '#/components/schemas/ParcelsReportFilter'
fields:
type: array
items:
$ref: '#/components/schemas/ParcelsReportFields'
url:
title: Url
maxLength: 65536
minLength: 1
type: string
description: URL to download the report.
format: uri
example: >-
https://reporting-service.s3.eu-central-1.amazonaws.com/reports/report-type/2021-08-09/afc46bb9-95d3-4880-80f7-660da3e68b5c.csv
expires_at:
type: string
title: Expires At
description: When the report will expire.
format: date-time
example: '2022-07-14T08:38:10.226217Z'
updated_at:
type: string
title: Updated At
description: When was the report last updated.
format: date-time
example: '2022-07-14T08:23:10.226265Z'
created_at:
type: string
title: Created At
description: When was the report created.
format: date-time
example: '2022-07-14T08:23:10.226265Z'
required:
- filters
- fields
ParcelsReportFields:
title: Parcel Report Fields
enum:
- parcel_id
- direction
- carrier_code
- carrier_name
- from_company_name
- contract_id
- contract_type
- origin_city
- origin_postal_code
- origin_country_code
- origin_country_name
- destination_city
- destination_postal_code
- destination_country_code
- destination_country_name
- order_number
- tracking_number
- created_at
- updated_at
- announced_at
- shipped_at
- first_delivery_at
- arrived_at
- shipping_method
- shipping_method_name
- price
- global_status_slug
- carrier_status
- integration_id
- integration_type
- weight
type: string
description: The parcel fields to include for the report
ParcelsReportFilter:
title: Parcels Report Filters Object
type: object
properties:
direction:
allOf:
- $ref: '#/components/schemas/ParcelDirections'
description: >-
Includes only the parcels that are sent (`outgoing`) or returned
(`incoming`).
integration_id:
type: integer
title: Integration Id
description: >-
Includes only the parcels created by the shop integration with the
provided id.
minimum: 1
updated_after:
title: Updated After
type: string
description: >
Includes only the parcels which have been updated in our system
after your given time.
You can use the value of ISO 8601 DateTime string like this:
- 2018-02-26T11:01:47.505309+00:00
- 2018-02-26T11:01:47
- 2018-02-26
Note: the default timezone is UTC
format: date-time
updated_before:
title: Updated Before
type: string
description: >
Includes only the parcels which have been updated in our system
before your given time.
You can use the value of ISO 8601 DateTime string like this:
- 2018-02-26T11:01:47.505309+00:00
- 2018-02-26T11:01:47
- 2018-02-26
Note: the default timezone is UTC
format: date-time
announced_after:
title: Announced After
type: string
description: >
Includes only the parcels which have been announced in our system
after your given time.
You can use the value of ISO 8601 DateTime string like this:
- 2018-02-26T11:01:47.505309+00:00
- 2018-02-26T11:01:47
- 2018-02-26
Note: the default timezone is UTC
format: date-time
announced_before:
title: Announced Before
type: string
description: >
Includes only the parcels which have been announced in our system
before your given time.
You can use the value of ISO 8601 DateTime string like this:
- 2018-02-26T11:01:47.505309+00:00
- 2018-02-26T11:01:47
- 2018-02-26
Note: the default timezone is UTC
format: date-time
description: A parcels report filter
ParcelsReportRequest:
title: Parcels Report Request Object
required:
- fields
- filters
type: object
properties:
fields:
type: array
items:
$ref: '#/components/schemas/ParcelsReportFields'
filters:
$ref: '#/components/schemas/ParcelsReportFilter'
description: A parcel report request
ReportStatus:
title: Report Status
enum:
- queued
- generating
- ready
- failed
- expired
type: string
description: The report status
Error:
title: Error
type: object
properties:
loc:
type: array
description: The location that the error occured
items:
type: string
example: path
msg:
type: string
example: value is not a valid uuid
description: A description of the error
type:
type: string
example: type_error.uuid
ctx:
type: object
description: Provides a list of possible fields to be used
properties:
enum_values:
type: array
items:
$ref: '#/components/schemas/ParcelsReportFields'
required:
- loc
- msg
- type
securitySchemes:
HTTPBasicAuth:
type: http
description: >-
Basic Authentication using API key and secrets is currently the main
authentication mechanism.
scheme: basic
OAuth2ClientCreds:
type: oauth2
description: >-
OAuth2 is a standardized protocol for authorization that allows users to
share their private resources stored on one site with another site
without having to provide their credentials. OAuth2 Client Credentials
Grant workflow. This workflow is typically used for server-to-server
interactions that require authorization to access specific resources.
flows:
clientCredentials:
tokenUrl: https://account.sendcloud.com/oauth2/token/
scopes:
api: Default OAuth scope required to access Sendcloud API.
responses:
'422':
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'