Sendcloud Reporting API

openapi: 3.2.0
info:
  title: Sendcloud Reporting API
  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
  version: '1.0'
  description: 'Operations tagged Reporting across 2 of this provider''s published API definitions: sendcloud-v2-reporting-openapi.yml, sendcloud-v3-reporting-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://panel.sendcloud.sc/api/v2
  description: Sendcloud Production
- url: https://panel.sendcloud.sc/api/v3
  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
    servers:
    - url: https://panel.sendcloud.sc/api/v2
      description: Sendcloud Production
  /reporting/parcels/{report_id}:
    parameters:
    - schema:
        type: integer
      name: report_id
      in: path
      required: true
      description: The report unique identifier
    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.\n\nDepending 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.\n    \nThe 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'
    servers:
    - url: https://panel.sendcloud.sc/api/v2
      description: Sendcloud Production
components:
  schemas:
    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
    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
    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
    HTTPError:
      title: HTTP Error Object
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/Error'
    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
    ParcelDirections:
      type: string
      title: Parcel Directions
      enum:
      - incoming
      - outgoing
      description: The direction of the parcel
      example: outgoing
    ReportStatus:
      title: Report Status
      enum:
      - queued
      - generating
      - ready
      - failed
      - expired
      type: string
      description: The report status
    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.\n\nYou can use the value of ISO 8601 DateTime string like this:\n - 2018-02-26T11:01:47.505309+00:00\n - 2018-02-26T11:01:47\n - 2018-02-26\n\nNote: the default timezone is UTC\n"
          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.\n\nYou can use the value of ISO 8601 DateTime string like this:\n - 2018-02-26T11:01:47.505309+00:00\n - 2018-02-26T11:01:47\n - 2018-02-26\n\nNote: the default timezone is UTC\n"
          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.\n\nYou can use the value of ISO 8601 DateTime string like this:\n - 2018-02-26T11:01:47.505309+00:00\n - 2018-02-26T11:01:47\n - 2018-02-26\n\nNote: the default timezone is UTC\n"
          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.\n\nYou can use the value of ISO 8601 DateTime string like this:\n - 2018-02-26T11:01:47.505309+00:00\n - 2018-02-26T11:01:47\n - 2018-02-26\n\nNote: the default timezone is UTC\n"
          format: date-time
      description: A parcels report filter
    ParcelsReportFields_2:
      type: string
      title: ParcelsReportFields
      description: A column that can be included in a parcels report.
      enum:
      - parcel_id
      - direction
      - carrier_code
      - carrier_name
      - from_address_company_name
      - contract_id
      - contract_type
      - from_address_city
      - from_address_postal_code
      - from_address_country_code
      - from_address_country_name
      - to_address_city
      - to_address_postal_code
      - to_address_country_code
      - to_address_country_name
      - order_number
      - tracking_number
      - announced_at
      - shipped_at
      - first_offer_at
      - delivered_at
      - shipping_option_code
      - total_cost
      - status
      - sub_status
      - integration_id
      - integration_type
      - weight
      - brand_id
      - brand_name
    ParcelsReportRequest_2:
      type: object
      title: ParcelsReportRequest
      description: Request body for creating a parcels report.
      properties:
        fields:
          type: array
          minItems: 1
          description: Columns to include in the CSV report, in the order they should appear.
          items:
            $ref: '#/components/schemas/ParcelsReportFields_2'
        filters:
          $ref: '#/components/schemas/ParcelsReportFilter_2'
      required:
      - fields
      - filters
    ParcelDirection:
      type: string
      title: ParcelDirection
      description: The direction of the parcel.
      enum:
      - incoming
      - outgoing
      example: outgoing
    ParcelsReport_2:
      type: object
      title: ParcelsReport
      description: Represents a parcels report and its processing state.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the report.
          example: 419f3be0-2f49-434b-bee4-d8cff9cf7d01
        organization_id:
          type: integer
          minimum: 1
          description: Identifier of the organization the report belongs to.
          example: 12345
        status:
          $ref: '#/components/schemas/ReportStatus_2'
        status_message:
          type: string
          description: Human-readable description of the current status.
          example: The report is ready
        fields:
          type: array
          description: Columns included in the report.
          items:
            $ref: '#/components/schemas/ParcelsReportFields_2'
        filters:
          $ref: '#/components/schemas/ParcelsReportFilter_2'
        url:
          type:
          - string
          - 'null'
          format: uri
          description: URL to download the CSV. `null` until the report status is `ready`, and again after expiry.
          example: https://reporting-service.s3.eu-central-1.amazonaws.com/reports/parcels_v3/2025-05-01/419f3be0-2f49-434b-bee4-d8cff9cf7d01.csv
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the report (and its download URL) will expire. `null` until the report is `ready`.
          example: '2025-05-01T08:38:10.226217Z'
        updated_at:
          type: string
          format: date-time
          description: When the report was last updated.
          example: '2025-05-01T08:24:10.226265Z'
        created_at:
          type: string
          format: date-time
          description: When the report was created.
          example: '2025-05-01T08:23:10.226265Z'
      required:
      - id
      - organization_id
      - status
      - status_message
      - fields
      - filters
    ErrorObject:
      title: Error
      type: object
      description: Error in a JSON:API error format
      properties:
        id:
          type: string
          description: A unique identifier for the error.
        links:
          type: object
          description: A set of hyperlinks that provide additional information about the error.
          properties:
            about:
              type: string
              description: A URL that provides additional information about the error.
        status:
          type: string
          format: int32
          description: The HTTP status code of the error.
          minLength: 1
        code:
          type: string
          description: A unique error code for the error, in snake case format.
          minLength: 1
          enum:
          - unknown_field
          - invalid
          - forbidden
          - invalid_choice
          - min_value
          - 'null'
          - not_found
          - required
          - not_a_list
          - non_field_errors
          - authentication_failed
          - validation_error
          - parcel_announcement_error
        title:
          type: string
          description: A short, human-readable summary of the error.
          minLength: 1
        detail:
          type: string
          description: A human-readable explanation of the error.
          minLength: 1
        source:
          type: object
          description: An object that identifies the source of the error within the request payload.
          properties:
            pointer:
              type: string
              description: A `JSON` pointer to the location of the error within the request payload.
            parameter:
              type: string
              description: The name of the `query` parameter that caused the error.
            header:
              type: string
              description: The name of the `header` parameter that caused the error.
        meta:
          type: object
          description: Additional metadata about the error.
    ReportStatus_2:
      type: string
      title: ReportStatus
      description: Current processing status of the report.
      enum:
      - queued
      - generating
      - ready
      - failed
      - expired
      example: ready
    errors:
      title: Errors
      type: object
      description: A standardized format for errors in JSON:API responses.
      properties:
        errors:
          type:
          - array
          - object
          items:
            type: object
            allOf:
            - $ref: '#/components/schemas/ErrorObject'
            required:
            - status
            - code
            - detail
    ParcelsReportFilter_2:
      type: object
      title: ParcelsReportFilter
      description: Filters that determine which parcels are included in the report.
      properties:
        announced_after:
          type: string
          format: date-time
          description: Include only parcels announced on or after this time (ISO 8601, UTC default).
          example: '2025-04-01T00:00:00Z'
        announced_before:
          type: string
          format: date-time
          description: Include only parcels announced on or before this time (ISO 8601, UTC default).
          example: '2025-04-30T23:59:59Z'
        direction:
          $ref: '#/components/schemas/ParcelDirection'
        integration_id:
          type: integer
          minimum: 1
          description: Filter to parcels created by a specific shop integration id.
          example: 1
        brand_id:
          type: integer
          minimum: 1
          description: Filter to parcels created by a specific brand id.
          example: 1
        shipping_option_code:
          type: string
          minLength: 1
          maxLength: 256
          description: Filter to parcels shipped with the given shipping option code.
          example: postnl_standard
        updated_after:
          type: string
          format: date-time
          description: Include only parcels updated on or after this time (ISO 8601, UTC default).
          example: '2025-04-01T00:00:00Z'
        updated_before:
          type: string
          format: date-time
          description: Include only parcels updated on or before this time (ISO 8601, UTC default).
          example: '2025-04-30T23:59:59Z'
      required:
      - announced_after
      - announced_before
  responses:
    '422':
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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.
x-refined-from:
- sendcloud-v2-reporting-openapi.yml
- sendcloud-v3-reporting-openapi.yml