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: contact@sendcloud.com
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: |-
OAuth2 scopes required: `read:analytics`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- read:analytics
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: |-
OAuth2 scopes required: `read:analytics`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- read:analytics
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:
read:analytics: View your shipping analytics
read:audit-log: View your account's audit log
read:brand: View your brands
write:brand: Manage your brands
write:carrier: Configure carriers and contracts
read:checkout: View your dynamic checkout configurations and templates
read:event-subscription: View your event subscriptions
write:event-subscription: Create and manage your event subscriptions
read:integration: View your integrations
write:integration: Connect and manage integrations
read:invoice: View your invoices
read:notification: View your notifications
write:notification: Manage your notifications
read:operational-settings: View your warehouses, shipping lanes, and other operational settings
write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
read:order: View your orders
write:order: Import and process your orders
read:organization: View organization settings
write:organization: Change organization settings
read:parcel: View your shipments and their tracking status
write:parcel: Create, announce, and cancel shipments
read:pickup: View carrier pickups and the options available for scheduling them
write:pickup: Schedule and manage carrier pickups
read:price: View shipping prices
write:product: Manage your product catalog
read:return: View your returns
write:return: Create and manage returns
read:return-settings: View your return settings
write:return-settings: Configure your return settings
read:service-point: View carrier service points
read:shipping-method: View shipping methods, products and prices
read:shipping-rule: View your shipping rules
write:shipping-rule: Create and manage shipping rules
read:support-ticket: View your support tickets
write:support-ticket: Manage your support tickets
read:tracking-message: View your tracking notifications
write:tracking-message: Manage your tracking notifications
read:tracking-page: View your tracking page
write:tracking-page: Customize your tracking page
read:user: Read your basic account information
responses:
'422':
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'