Sendcloud
Sendcloud Parcels API

Get insights about parcels
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: Shipments Address Parcels API
  version: 3.0.0
  description: The Shipments API allows you to create and announce, retrieve, and cancel outgoing shipments and their associated parcels within the Sendcloud platform.
  contact:
    name: Sendcloud API Support
    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/v3
  description: Sendcloud Production
tags:
- name: Parcels
  description: Get insights about parcels
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/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/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
  /parcels:
    get:
      summary: Retrieve parcels
      x-sendcloud-paginated: true
      x-sendcloud-paginated-discriminator: parcels
      x-mint:
        href: /api/v2/parcels/retrieve-parcels
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>"
      tags:
      - Parcels
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: Retrieve parcels
                type: object
                properties:
                  next:
                    type: integer
                    nullable: true
                  previous:
                    type: integer
                    nullable: true
                  parcels:
                    type: array
                    uniqueItems: true
                    minItems: 1
                    items:
                      $ref: '#/components/schemas/ParcelResponseShort'
                required:
                - parcels
              examples:
                RetrieveParcels:
                  summary: Retrieve parcels
                  value:
                    next: null
                    previous: null
                    parcels:
                    - id: 3172
                      name: John Doe
                      company_name: Sendcloud
                      contract: 1
                      address: Stadhuisplein 10
                      address_divided:
                        street: Stadhuisplein
                        house_number: '10'
                      city: Eindhoven
                      postal_code: 5611 EM
                      telephone: 0612345678
                      email: test@email.com
                      date_created: 01-01-2018 21:45:30
                      date_updated: 01-01-2018 21:47:12
                      date_announced: 01-01-2018 21:47:13
                      tracking_number: S0M3TR4Ck1NgNumB3r
                      customs_declaration: {}
                      weight: '2.000'
                      label:
                        normal_printer:
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=0&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=1&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=2&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=3&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        label_printer: https://panel.sendcloud.sc/api/v2/label/label_printer/3172?hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                      status:
                        id: 0
                        message: Ready to send
                      data: {}
                      country:
                        iso_3: NLD
                        iso_2: NL
                        name: Netherlands
                      shipment:
                        id: 1
                        name: PostNL Standard 0-23kg
                      carrier:
                        code: postnl
                      colli_uuid: ab3ecb5e-61b6-42b1-8034-7c6befdeaa63
                      collo_nr: 0
                      collo_count: 1
                      reference: some_reference_123
                RetrieveParcelsVerbose:
                  summary: Get all parcels when `errors` query param is `verbose-carrier`
                  value:
                    next: null
                    previous: null
                    parcels:
                    - id: 3172
                      name: John Doe
                      company_name: Sendcloud
                      contract: 1
                      address: Stadhuisplein 10
                      address_divided:
                        street: Stadhuisplein
                        house_number: '10'
                      city: Eindhoven
                      postal_code: 5611 EM
                      telephone: 0612345678
                      email: test@email.com
                      date_created: 01-01-2018 21:45:30
                      date_updated: 01-01-2018 21:47:12
                      date_announced: 01-01-2018 21:47:13
                      tracking_number: S0M3TR4Ck1NgNumB3r
                      customs_declaration: {}
                      weight: '2.000'
                      label:
                        normal_printer:
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=0&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=1&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=2&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=3&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        label_printer: https://panel.sendcloud.sc/api/v2/label/label_printer/3172?hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                      status:
                        id: 0
                        message: Ready to send
                      data: {}
                      country:
                        iso_3: NLD
                        iso_2: NL
                        name: Netherlands
                      shipment:
                        id: 1
                        name: PostNL Standard 0-23kg
                      carrier:
                        code: postnl
                      colli_uuid: ab3ecb5e-61b6-42b1-8034-7c6befdeaa63
                      collo_nr: 0
                      collo_count: 1
                      reference: some_reference_123
                      errors:
                        non_field_errors:
                        - 'PostNL service error: The domain for email address johndoe@email.com seems to be invalid.'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                      request:
                        type: string
                      message:
                        type: string
              examples:
                InvalidCursor:
                  summary: Invalid cursor
                  value:
                    error:
                      code: 404
                      request: api/v2/parcels
                      message: Invalid cursor
      operationId: sc-public-v2-scp-get-all_parcels
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      description: This endpoint allows you to retrieve a list of all the parcels which you have created or imported into your Sendcloud account under your API credentials. You can filter the results based on the query parameters provided below, in order to retrieve a specific parcel or list of parcels which match the defined criteria.
      parameters:
      - in: query
        name: parcel_status
        description: Returns parcels that have the requested status. For a list of possible statuses, see the [Retrieve a list of parcel statuses](/api/v2/parcel-statuses/retrieve-a-list-of-parcel-statuses) endpoint.
        schema:
          type: integer
      - schema:
          type: string
        in: query
        name: tracking_number
        description: Returns parcels that match a specified tracking number
      - schema:
          type: string
        in: query
        name: external_reference
        description: Returns parcels that match a specified external reference
      - schema:
          type: string
        in: query
        name: order_number
        description: Returns an order that matches a specific `order_number` property from your parcels
      - schema:
          type: string
          example: '2018-02-26T11:01:47.505309+00:00'
        in: query
        name: updated_after
        description: Returns all orders which have been updated in our system after a given time. You can use the value of ISO 8601 DateTime string like this
      - schema:
          type: string
          example: '2018-02-26T11:01:47.505309+00:00'
        in: query
        name: announced_after
        description: Returns all orders which have been announced to the carrier after the given time. You can use the value of ISO 8601 DateTime string like this
      - schema:
          type: string
        in: query
        name: ids
        description: Filter results using a list of Parcel IDs. This is a comma separated list of IDs, it may not contain more then 100 IDs.
      - schema:
          type: string
        in: query
        name: cursor
        description: Next and previous token that is used to paginate. The token is included in the response.
      - schema:
          type: string
          enum:
          - verbose-carrier
        in: query
        name: errors
        description: If you are using this API for development purposes, you might want to use the errors query string in the URL. This allows you to visualize errors from the carrier.
    post:
      summary: Create a parcel or parcels
      tags:
      - Parcels
      operationId: sc-public-v2-scp-post-create_parcel
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/parcels/create-a-parcel-or-parcels
        content: "<Danger>\n  **This endpoint is now in maintenance mode and is closed to new users.** \n\n  - If your Sendcloud account was created before April 13th 2026, you can continue to use this endpoint as normal.\n  - New users should start with API v3 to access our latest features and improved\n  performance.\n  \n  Read more about\n  [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API\n  v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Danger>\n\nThis endpoint **creates a parcel** under your API credentials.\n\n- You can choose to **announce the parcel** and create the shipping label at the same time as you create the parcel by providing the parameter `request_label: true`. \n- When `request_label` is `false`, the parcel will be created, but not announced.\n- You can then request the shipping label at a later date by changing the `request_label` parameter via the [Update a parcel](/api/v2/parcels/update-a-parcel) endpoint.\n\n<Warning>\n  Make sure you use the correct `sender_address` if you wish to ship this parcel from a location **other than** your **default** sender address. You can find the `sender_address` for each of the addresses you've saved in your Sendcloud account via the [Retrieve a sender address](/api/v2/sender-addresses/get-a-sender-address) endpoint.\n</Warning>\n\n<Warning>\n  Also keep in mind that the `sender_address` id will not be saved/reflected in the created order (Incoming Orders view / Pack & Go) if `request_label` is `false`.\n</Warning>\n\n## International parcel creation\n\nIf you want to create a parcel to ship to a destination country outside the EU, it's mandatory to include additional information related to the parcel contents. This allows Sendcloud to automatically generate the required customs documentation based on the international shipping method selected. After the shipping label and associated documents are generated, you can retrieve and download them via the [Retrieve parcel documents](/api/v2/parcel-documents/retrieve-parcel-documents) endpoint.\n\n<Warning>\n  If you have more than one active contracts for a specific carrier, you must fill the `contract` field with your desired contract ID in your request. You can get your contract ID from the [Retrieve a list of contracts](/api/v2/contracts/retrieve-a-list-of-contracts) endpoint.\n</Warning>\n\n<Info>\n  International parcels require more information than domestic parcels. Certain customs documents must be created when shipping to countries outside the EU. For Sendcloud to successfully generate these documents, all the necessary information must be available in your parcel request. You can read more in-depth information on international shipping and its requirements in [our developer guides](/docs/shipping/international-shipping/).\n</Info>\n\n## Multicollo\n\nMore information on how to create multiple parcels within one shipment can be found in the [Multicollo page](/docs/shipping/multicollo/) of our developer guides."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: Create a parcel
                oneOf:
                - type: object
                  title: Failed to create parcels response
                  properties:
                    failed_parcels:
                      type: array
                      uniqueItems: true
                      items:
                        properties:
                          parcel:
                            $ref: '#/components/schemas/ParcelResponseFull'
                          errors:
                            type: object
                        type: object
                - type: object
                  title: Single parcel created response
                  properties:
                    parcel:
                      $ref: '#/components/schemas/ParcelResponseFull'
                - type: object
                  title: Batch of parcels created response
                  properties:
                    parcels:
                      type: array
                      uniqueItems: true
                      items:
                        $ref: '#/components/schemas/ParcelResponseFull'
              examples:
                CreateParcel:
                  summary: Parcel created
                  value:
                    parcel:
                      id: 3
                      name: John Doe
                      company_name: Sendcloud
                      contract: 1
                      address: Stadhuisplein 10
                      address_divided:
                        street: Stadhuisplein
                        house_number: '10'
                      city: Eindhoven
                      postal_code: 5611 EM
                      telephone: 0612345678
                      email: ''
                      date_created: 01-01-2018 21:45:30
                      date_updated: 01-01-2018 21:47:12
                      date_announced: 01-01-2018 21:47:13
                      tracking_number: S0M3TR4Ck1NgNumB3r
                      weight: '2.000'
                      label:
                        normal_printer:
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=0&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=1&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=2&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        - https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=3&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                        label_printer: https://panel.sendcloud.sc/api/v2/label/label_printer/3172?hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                      documents:
                      - type: label
                        size: a6
                        link: https://panel.sendcloud.sc/api/v2/parcels/3/documents/label
                      status:
                        id: 0
                        message: Ready to send
                      data: {}
                      country:
                        iso_3: NLD
                        iso_2: NL
                        name: Netherlands
                      shipment:
                        id: 1
                        name: PostNL Standard 0-23kg
                      carrier:
                        code: postnl
                      is_return: false
                      total_order_value_currency: GBP
                      total_order_value: '11.11'
                      colli_uuid: 88296eff-595c-4c62-9b6f-075112bf54f6
                      collo_nr: 0
                      collo_count: 1
                      awb_tracking_number: null
                      box_number: null
                      length: null
                      width: null
                      height: null
                      shipping_method_checkout_name: DHL Express Domestic
                      reference: some_reference_123
                CreateParcels:
                  summary: Create multiple parcels with verbose errors
                  value:
                    failed_parcels:
                    - parcel:
                        id: 5
                        name: John Doe
                        company_name: Sendcloud
                        address_divided:
                          street: Stadhuisplein 10
                          house_number: ''
                        city: Eindhoven
                        postal_code: 5611 EM
                        telephone: '+31612345678'
                        email: ''
                        date_created: 01-01-2018 21:45:30
                        date_updated: 01-01-2018 21:45:30
                        date_announced: 01-01-2018 21:45:30
                        tracking_number: S0M3TR4Ck1NgNumB3r
                        weight: '10.000'
                        reference: some_reference_123
                      errors:
                        house_number:
                        - This field may not be blank.
                CreateParcelVerboseCarrier:
                  summary: Create single parcel with carrier verbosity
                  value:
                    parcel:
                      address: Stadhuisplein 10
                      address_2: ''
                      address_divided:
                        house_number: '10'
                        street: Stadhuisplein
                      carrier:
                        code: dhl
                      city: Eindhoven
                      company_name: Sendcloud
                      contract: 1
                      country:
                        iso_2: NL
                        iso_3: NLD
                        name: Netherlands
                      customs_invoice_nr: ''
                      customs_shipment_type: 2
                      data: {}
                      date_created: 05-06-2018 11:27:55
                      date_updated: 05-06-2018 11:27:55
                      date_announced: 05-06-2018 11:31:16
                      email: john@doe.com
                      id: 22
                      insured_value: 0
                      label:
                        label_printer: https://panel.sendcloud.sc/api/v2/labels/label_printer/22
                        normal_printer:
                        - https://panel.sendcloud.sc/api/v2/labels/normal_printer/22?start_from=0
                        - https://panel.sendcloud.sc/api/v2/labels/normal_printer/22?start_from=1
                        - https://panel.sendcloud.sc/api/v2/labels/normal_printer/22?start_from=2
                        - https://panel.sendcloud.sc/api/v2/labels/normal_printer/22?start_from=3
                      name: John Doe
                      order_number: ''
                      shipment_uuid: 928a46f4-8891-4c09-8889-6d0f7c1dc01c
                      parcel_items: []
                      postal_code: 5611 EM
                      shipment:
                        id: 8
                        name: Unstamped letter
                      status:
                        id: 11
                        message: De

# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-parcels-api-openapi.yml
Sendcloud Parcels API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification
