openapi: 3.1.0
info:
  title: Analytics
  version: 2.0.0
  description: >-
    The Analytics API lets you query for insights about parcels, products and
    transit times.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: contact@sendcloud.com
servers:
  - url: https://panel.sendcloud.sc/api/v2
    description: Sendcloud Production
tags:
  - name: Parcels
    description: Get insights about parcels
  - name: Products
    description: Get insights about products
  - name: Transit times
    description: Get insights about average transit times per carriers and shipping methods
  - name: User Carriers and Shipping Methods
    description: Get list of carriers and shipping methods a user ever used
paths:
  /insights/parcels/series:
    get:
      summary: Retrieve parcel-insights series
      tags:
        - Parcels
      x-mint:
        href: /api/v2/analytics/retrieve-parcel-insights-series
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Series'
              examples:
                Series:
                  summary: Series
                  value:
                    series:
                      - value: 358
                        start_date: '2017-12-10'
                        end_date: '2020-12-10'
                        missing_data:
                          - start_date: '2018-12-10'
                            end_date: '2019-12-10'
                            reason_code: not-available
                          - start_date: '2019-12-10'
                            end_date: '2020-12-10'
                            reason_code: partly-available
                      - value: 188
                        start_date: '2021-12-10'
                        end_date: '2022-12-10'
                        missing_data:
                          - start_date: '2021-12-10'
                            end_date: '2022-12-10'
                            reason_code: missing-filter-property
        '422':
          description: Unprocessable Entity (WebDAV)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequest:
                  summary: Bad request
                  value:
                    detail:
                      - loc:
                          - query
                          - start_date
                        msg: field required
                        type: value_error.missing
      operationId: sc-public-v2-analytics-get-parcels_series
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      description: >-
        Returns data about parcels as a series, e.g. the number of parcels per
        day/month/year over a specified period.
      parameters:
        - schema:
            type: string
            format: date
          in: query
          name: start_date
          required: true
          description: period start date
        - schema:
            type: string
            format: date
          in: query
          name: end_date
          required: true
          description: period end date
        - schema:
            type: string
            example: postnl
          in: query
          name: carrier_code
          description: filter by carrier
        - schema:
            type: string
            example: DE
          in: query
          name: from_country
          description: origin country
        - schema:
            type: string
            example: NL
          in: query
          name: to_country
          description: destination country
        - schema:
            type: array
            items:
              type: integer
              example: 124523
          allowEmptyValue: true
          in: query
          name: integration_id
          description: integrations
        - schema:
            type: string
            enum:
              - days
              - months
              - years
          in: query
          name: granularity
          description: the size of one point
          required: true
        - schema:
            type: string
            enum:
              - incoming
              - outgoing
          in: query
          name: direction
          description: incoming or outgoing
        - schema:
            type: array
            items:
              type: integer
          in: query
          name: brand_id
          description: filtering by brand id
          allowEmptyValue: true
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_name
          description: filtering by product name
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_sku
          description: filtering by product sku
  /insights/products/series:
    get:
      summary: Retrieve product-insights series
      tags:
        - Products
      x-mint:
        href: /api/v2/analytics/retrieve-product-insights-series
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Series'
              examples:
                Series:
                  summary: Series
                  value:
                    series:
                      - value: 358
                        start_date: '2017-12-10'
                        end_date: '2020-12-10'
                        missing_data:
                          - start_date: '2018-12-10'
                            end_date: '2019-12-10'
                            reason_code: not-available
                          - start_date: '2019-12-10'
                            end_date: '2020-12-10'
                            reason_code: partly-available
                      - value: 188
                        start_date: '2021-12-10'
                        end_date: '2022-12-10'
                        missing_data:
                          - start_date: '2021-12-10'
                            end_date: '2022-12-10'
                            reason_code: missing-filter-property
        '422':
          description: Unprocessable Entity (WebDAV)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequest:
                  summary: Bad request
                  value:
                    detail:
                      - loc:
                          - query
                          - start_date
                        msg: field required
                        type: value_error.missing
      operationId: sc-public-v2-analytics-get-products_series
      description: >-
        Returns data about products as a series, e.g. the number of products per
        day/month/year over a specified period.
      security: []
      parameters:
        - schema:
            type: string
            format: date
          in: query
          name: start_date
          required: true
          description: period start date
        - schema:
            type: string
            format: date
          in: query
          name: end_date
          required: true
          description: period end date
        - schema:
            type: string
            example: postnl
          in: query
          name: carrier_code
          description: filter by carrier
        - schema:
            type: string
            example: DE
          in: query
          name: from_country
          description: origin country
        - schema:
            type: string
            example: NL
          in: query
          name: to_country
          description: destination country
        - schema:
            type: array
            items:
              type: integer
              example: 124523
          allowEmptyValue: true
          in: query
          name: integration_id
          description: integrations
        - schema:
            type: string
            enum:
              - days
              - months
              - years
          in: query
          name: granularity
          description: the size of one point
          required: true
        - schema:
            type: string
            enum:
              - incoming
              - outgoing
          in: query
          name: direction
          description: incoming or outgoing
        - schema:
            type: array
            items:
              type: integer
          in: query
          name: brand_id
          description: filtering by brand id
          allowEmptyValue: true
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_name
          description: filtering by product name
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_sku
          description: filtering by product sku
  /insights/parcels/buckets:
    get:
      summary: Retrieve parcel-insights buckets
      tags:
        - Parcels
      x-mint:
        href: /api/v2/analytics/retrieve-parcel-insights-buckets
      description: >-
        Returns data about parcels as buckets. Buckets should be grouped by any
        category, for example by country.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Buckets'
              examples:
                Buckets:
                  summary: Buckets
                  value:
                    buckets:
                      - key: UK
                        value: 10
                        percentage: 12.24
                        missing_data:
                          - start_date: '2018-12-10'
                            end_date: '2019-12-10'
                            reason_code: partly-available
                      - key: DE
                        value: 8
                        percentage: 9.85
                        missing_data:
                          - start_date: '2018-12-10'
                            end_date: '2019-12-10'
                            reason_code: not-available
                BucketsGroupedByCountryRoutes:
                  summary: Buckets grouped by country routes
                  value:
                    buckets:
                      - key: UK-DE
                        value: 34
                        percentage: 12.24
                        missing_data:
                          - start_date: '2018-12-10'
                            end_date: '2019-12-10'
                            reason_code: partly-available
                      - key: AT-NL
                        value: 25
                        percentage: 9.85
                        missing_data: []
        '422':
          description: Unprocessable Entity (WebDAV)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequest:
                  summary: Bad Request
                  value:
                    detail:
                      - loc:
                          - query
                          - start_date
                        msg: field required
                        type: value_error.missing
      operationId: sc-public-v2-analytics-get-parcels_buckets
      parameters:
        - schema:
            type: string
            format: date
          in: query
          name: start_date
          description: period start date (announced)
          required: true
        - schema:
            type: string
            format: date
          in: query
          name: end_date
          description: period end date (announced)
          required: true
        - schema:
            type: string
            example: postnl
          in: query
          name: carrier_code
          description: filter by carriers
        - schema:
            type: string
            example: DE
          in: query
          name: from_country
          description: origin country code
        - schema:
            type: string
            example: NL
          in: query
          name: to_country
          description: destination country code
        - schema:
            type: array
            items:
              type: integer
              example: 124523
          allowEmptyValue: true
          in: query
          name: integration_id
          description: integrations
        - schema:
            type: string
            enum:
              - to_country
              - from_country
              - carrier
              - integration
              - direction
              - route
              - brand
          in: query
          name: group_by
          description: group by category
          required: true
        - schema:
            type: string
            minLength: 0
            example: '5'
          in: query
          name: size
          description: number of the buckets
        - schema:
            type: string
            enum:
              - incoming
              - outgoing
          in: query
          name: direction
          description: incoming or outgoing
        - schema:
            type: array
            items:
              type: integer
          in: query
          name: brand_id
          description: filtering by brand id
          allowEmptyValue: true
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_name
          description: filtering by product name
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_sku
          description: filtering by product sku
      security: []
  /insights/products/buckets:
    get:
      summary: Retrieve product-insights buckets
      tags:
        - Products
      x-mint:
        href: /api/v2/analytics/retrieve-product-insights-buckets
      description: >-
        Returns data about products as buckets. Buckets should be grouped by any
        category, for example by country.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Buckets'
              examples:
                Buckets:
                  summary: Buckets
                  value:
                    buckets:
                      - key: UK
                        value: 10
                        percentage: 12.24
                        missing_data:
                          - start_date: '2018-12-10'
                            end_date: '2019-12-10'
                            reason_code: partly-available
                      - key: DE
                        value: 8
                        percentage: 9.85
                        missing_data:
                          - start_date: '2018-12-10'
                            end_date: '2019-12-10'
                            reason_code: partly-available
        '422':
          description: Unprocessable Entity (WebDAV)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequest:
                  summary: Unprocessable Entity (WebDAV)
                  value:
                    detail:
                      - loc:
                          - query
                          - start_date
                        msg: field required
                        type: value_error.missing
      operationId: sc-public-v2-analytics-get-products_buckets
      parameters:
        - schema:
            type: string
            format: date
          in: query
          name: start_date
          description: period start date (announced)
          required: true
        - schema:
            type: string
            format: date
          in: query
          name: end_date
          description: period end date (announced)
          required: true
        - schema:
            type: string
            example: postnl
          in: query
          name: carrier_code
          description: filter by carriers
        - schema:
            type: string
            example: DE
          in: query
          name: from_country
          description: origin country code
        - schema:
            type: string
            example: NL
          in: query
          name: to_country
          description: destination country code
        - schema:
            type: array
            items:
              type: integer
              example: 124523
          allowEmptyValue: true
          in: query
          name: integration_id
          description: integrations
        - schema:
            type: string
            enum:
              - integration
              - description
              - return_reason
              - brand
          in: query
          name: group_by
          description: group by category
          required: true
        - schema:
            type: string
            minLength: 0
            example: '5'
          in: query
          name: size
          description: number of the buckets
        - schema:
            type: string
            enum:
              - incoming
              - outgoing
          in: query
          name: direction
          description: incoming or outgoing
        - schema:
            type: array
            items:
              type: integer
          in: query
          name: brand_id
          description: filtering by brand id
          allowEmptyValue: true
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_name
          description: filtering by product name
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_sku
          description: filtering by product sku
      security: []
  /insights/parcels/counts-summary:
    get:
      summary: Retrieve parcels counts summary
      x-mint:
        href: /api/v2/analytics/retrieve-parcels-counts-summary
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Summary'
              examples:
                Summary:
                  summary: Summary
                  value:
                    summary:
                      - last_days: 7
                        value: 368
                      - last_days: 14
                        value: 668
                      - last_days: 30
                        value: 1253
        '422':
          description: Unprocessable Entity (WebDAV)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequest:
                  summary: Unprocessable Entity (WebDAV)
                  value:
                    detail:
                      - loc:
                          - query
                          - last-days
                        msg: field required
                        type: value_error.missing
      operationId: sc-public-v2-analytics-get-parcels_summary
      description: Returns number of parcels for the last number of days selected.
      tags:
        - Parcels
      security: []
      parameters:
        - schema:
            type: string
            example: postnl
          in: query
          name: carrier_code
          description: filter by carrier
        - schema:
            type: string
            example: DE
          in: query
          name: from_country
          description: origin country
        - schema:
            type: string
            example: NL
          in: query
          name: to_country
          description: destination country
        - schema:
            type: array
            items:
              type: integer
              example: 124523
          allowEmptyValue: true
          in: query
          name: integration_id
          description: integrations
        - schema:
            type: integer
          in: query
          name: last_days
          required: true
          description: value for the last number of days
        - schema:
            type: string
            enum:
              - incoming
              - outgoing
          in: query
          name: direction
          description: incoming or outgoing parcels
        - schema:
            type: array
            items:
              type: integer
          in: query
          name: brand_id
          description: filtering by brand id
          allowEmptyValue: true
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_name
          description: filtering by product name
        - schema:
            type: array
            items:
              type: string
          in: query
          name: product_sku
          description: filtering by product sku
  /insights/carriers/transit-times:
    get:
      summary: Retrieve carrier transit times
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierTransitTime'
              examples:
                TransitTimes:
                  summary: Retrieve Carriers transit times
                  value:
                    transit_times:
                      - user_id: '1234'
                        carrier_code: postnl
                        from_country: NL
                        to_country: DE
                        start_date: '2022-12-31'
                        end_date: '2023-11-17'
                        total_parcels: 2406
                        transit_time: 82
                      - user_id: '1234'
                        carrier_code: dhl
                        from_country: DE
                        to_country: AT
                        start_date: '2021-12-31'
                        end_date: '2022-12-31'
                        total_parcels: 75422
                        transit_time: 51
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ValidationError:
                  summary: Validation error
                  value:
                    detail:
                      - loc:
                          - query
                          - carrier-code
                        msg: field required
                        type: value_error.missing
      operationId: sc-public-v2-analytics-get-carrier_transit_times
      description: >-
        Retrieves the average transit time of a parcel per carrier.

        You can filter the results by origin and destination country, as well as
        by start and end dates.
      tags:
        - Transit times
      x-mint:
        href: /api/v2/analytics/retrieve-carrier-transit-times
      security:
        - HTTPBasicAuth: []
      parameters:
        - schema:
            type: array
            items:
              type: string
              example: postnl
          in: query
          name: carrier_code
          description: selection of carriers
          required: true
        - schema:
            type: string
            example: DE
          in: query
          name: from_country
          description: origin country
        - schema:
            type: string
            example: NL
          in: query
          name: to_country
          description: destination country
        - schema:
            type: string
            format: date
            example: '2020-12-31'
          in: query
          name: start_date
          description: first delivery start date
        - schema:
            type: string
            format: date
            example: '2022-12-31'
          in: query
          name: end_date
          description: first delivery end date
  /insights/shipping-methods/transit-times:
    get:
      summary: Retrieve shipping method transit times
      x-mint:
        href: /api/v2/analytics/retrieve-shipping-method-transit-times
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingMethodTransitTime'
              examples:
                TransitTimes:
                  summary: Retrieve Shipping method transit times
                  value:
                    transit_times:
                      - user_id: '1234'
                        carrier_code: postnl
                        shipping_method_code: postnl:standard/kg=0-23
                        from_country: NL
                        to_country: DE
                        start_date: '2022-12-31'
                        end_date: '2023-12-31'
                        total_parcels: 240
                        transit_time: 92
                      - user_id: '1234'
                        carrier_code: dhl
                        shipping_method_code: dhl:complete/standard
                        from_country: DE
                        to_country: AT
                        start_date: '2022-12-31'
                        end_date: '2023-12-31'
                        total_parcels: 752
                        transit_time: 53
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ValidationError:
                  summary: Validation Error
                  value:
                    detail:
                      - loc:
                          - query
                          - carrier-code
                        msg: field required
                        type: value_error.missing
                      - loc:
                          - query
                          - shipping-method-code
                        msg: field required
                        type: value_error.missing
      operationId: sc-public-v2-analytics-get-shipping_method_transit_times
      description: >-
        Retrieves the average transit time of a parcel per shipping method and
        carrier.

        You can filter the results by origin and destination country, as well as
        start and end dates.
      tags:
        - Transit times
      security:
        - HTTPBasicAuth: []
      parameters:
        - schema:
            type: array
            items:
              type: string
              example: postnl:standard/kg=0-23
          in: query
          name: shipping_method_code
          description: selection of shipping methods
          required: true
        - schema:
            type: string
            example: DE
          in: query
          name: from_country
          description: origin country
        - schema:
            type: string
            example: NL
          in: query
          name: to_country
          description: destination country
        - schema:
            type: string
            format: date
            example: '2021-12-31'
          in: query
          name: start_date
          description: first delivery start date
        - schema:
            type: string
            format: date
            example: '2022-12-31'
          in: query
          name: end_date
          description: first delivery end date
  /analytics/shipping-methods:
    get:
      summary: Retrieve all shipping methods used by user
      x-mint:
        href: /api/v2/analytics/retrieve-all-shipping-methods-used-by-user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserShippingMethods'
              examples:
                TransitShippingTimes:
                  summary: Retrieve all shipping methods used by user
                  value:
                    shipping_methods:
                      - code: postnl:standard/kg=0-23
                        carrier_code: postnl
                      - code: dhl:complete/standard
                        carrier_code: dhl
      operationId: sc-public-v2-analytics-get-user_shipping_methods
      description: Returns a list of all shipping methods ever used by a user.
      tags:
        - User Carriers and Shipping Methods
      security: []
  /analytics/carriers:
    get:
      summary: Retrieve all carriers used by user
      x-mint:
        href: /api/v2/analytics/retrieve-all-carriers-used-by-user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCarriers'
              examples:
                Carriers:
                  summary: Retrieve all carriers used by user
                  value:
                    carriers:
                      - code: postnl
                      - code: dhl
      operationId: sc-public-v2-analytics-get-user_carriers
      description: Returns a list of all carriers ever used by a user.
      tags:
        - User Carriers and Shipping Methods
      security: []
components:
  schemas:
    Errors:
      title: Errors Object
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
    ErrorItem:
      title: Error Item Object
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            type: string
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
    Series:
      type: object
      title: Analytics Series Object
      description: Parcels/Products data represented in series
      properties:
        series:
          type: array
          items:
            type: object
            properties:
              value:
                type: integer
                example: 0
                minimum: 0
                description: Number of parcels/products for the period
              start_date:
                type: string
                format: date
              end_date:
                type: string
                format: date
              missing_data:
                type: array
                items:
                  type: object
                  description: Periods when data is missing
                  properties:
                    start_date:
                      type: string
                      format: date
                    end_date:
                      type: string
                      format: date
                    reason_code:
                      type: string
                      enum:
                        - missing-grouping-property
                        - missing-filter-property
                        - not-available
                        - partly-available
            required:
              - value
              - start_date
              - end_date
              - missing_data
      required:
        - series
    Buckets:
      type: object
      title: Analytics Buckets Object
      description: Parcel/Products data grouped into buckets.
      properties:
        buckets:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
                description: bucket key
              value:
                type: integer
                minimum: 0
                description: Number of parcels/products in bucket
              percentage:
                type: number
                minimum: 0
                description: Percent of all parcels/products this bucket has
              missing_data:
                type: array
                description: Periods when data is missing
                items:
                  type: object
                  properties:
                    start_date:
                      type: string
                      format: date
                    end_date:
                      type: string
                      format: date
                    reason_code:
                      type: string
                      enum:
                        - missing-grouping-property
                        - missing-filter-property
                        - not-available
                        - partly-available
            required:
              - key
              - value
              - percentage
              - missing_data
      required:
        - buckets
    Summary:
      type: object
      title: Analytics Summary Object
      description: Summary value for the selected last number of days
      properties:
        summary:
          type: array
          items:
            type: object
            description: Shows number of parcels for selected number of last days
            properties:
              last_days:
                type: integer
                minimum: 0
              value:
                type: integer
                minimum: 0
            required:
              - last_days
              - value
      required:
        - summary
    CarrierTransitTime:
      type: object
      title: User Carrier Transit Times Object
      properties:
        transit_times:
          type: array
          description: array of transit time objects
          items:
            type: object
            properties:
              user_id:
                type: string
                example: '12345'
              carrier_code:
                type: string
                example: postnl
              to_country:
                type: string
                example: DE
              from_country:
                type: string
                example: NL
              start_date:
                type: string
                format: date
              end_date:
                type: string
                format: date
              total_parcels:
                type: integer
                description: total number of parcels matching the filters
                minimum: 0
              transit_time:
                type: number
                description: average transit times for the matching parcels
                minimum: 0
            required:
              - user_id
              - carrier_code
              - total_parcels
              - transit_time
      required:
        - transit_times
    ShippingMethodTransitTime:
      type: object
      title: User Shipping Method Transit Times Object
      properties:
        transit_times:
          type: array
          description: array of transit time objects
          items:
            type: object
            properties:
              user_id:
                type: string
                example: '12345'
              carrier_code:
                type: string
                example: postnl
              shipping_method_code:
                type: string
                example: express-postnl-1-3kg
              from_country:
                type: string
                example: ES
              to_country:
                type: string
                example: AT
              start_date:
                type: string
                format: date
              end_date:
                type: string
                format: date
              total_parcels:
                type: integer
                description: total number of parcels matching the filters
                minimum: 0
              transit_time:
                type: number
                description: average transit times for the matching parcels
                minimum: 0
            required:
              - user_id
              - shipping_method_code
              - total_parcels
              - transit_time
      required:
        - transit_times
    UserShippingMethods:
      type: object
      description: All shipping methods used by user
      title: User Shipping Methods Object
      properties:
        shipping_methods:
          type: array
          description: array of shipping method objects
          items:
            type: object
            properties:
              code:
                type: string
                example: express-postnl-1-3kg
              carrier_code:
                type: string
                example: postnl
            required:
              - code
              - carrier_code
      required:
        - shipping_methods
    UserCarriers:
      type: object
      description: All carriers used by user
      properties:
        carriers:
          type: array
          description: array of carrier objects
          items:
            type: object
            properties:
              code:
                type: string
                example: postnl
            required:
              - code
      required:
        - carriers
  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.