Sendcloud Analytics API v2
Legacy v2 Analytics surface exposing aggregated shipping metrics.
OpenAPI Specification
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: [email protected]
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
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-v2-analytics-openapi.yml