> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve parcels

> 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.

<Warning>
  **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).
</Warning>


## OpenAPI

````yaml /.openapi/v2/parcels/openapi.yaml get /parcels
openapi: 3.1.0
info:
  title: Parcels
  version: 2.0.0
  description: >
    At the core of the Sendcloud Shipping API is the Parcels resource. Parcels
    are data objects which can be announced, and have a shipping method and
    shipping label assigned to them. You can also think of parcels as
    **shipments**.

    You can use this resource to perform a number of activities:


    * Create a parcel and immediately announce it

    * Create a parcel and choose not to announce it (no shipping label is
    created)

    * Update the details, or create a label, for an unannounced parcel

    * Cancel an announced parcel


    <!-- theme: info -->

    > 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. Read more
    in-depth information on [international shipping and its
    requirements](/docs/shipping/international-shipping/).
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://panel.sendcloud.sc/api/v2
    description: Sendcloud Production
security: []
tags:
  - name: Parcels
paths:
  /parcels:
    get:
      tags:
        - Parcels
      summary: Retrieve parcels
      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.
      operationId: sc-public-v2-scp-get-all_parcels
      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.
      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
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
components:
  schemas:
    ParcelResponseShort:
      description: Parcel object model
      type: object
      title: Parcel Object
      properties:
        address:
          type: string
        address_2:
          type: string
          description: >
            An apartment or floor number that has been extracted from general
            address input.
        address_divided:
          $ref: '#/components/schemas/AddressDivided'
        carrier:
          type: object
          properties:
            code:
              $ref: '#/components/schemas/carrier'
        city:
          type: string
        company_name:
          type: string
        contract:
          type: integer
          minimum: 1
          description: Id of the contract that was used to create the parcel.
          nullable: true
        country:
          $ref: '#/components/schemas/Country'
        customs_invoice_nr:
          type: string
          description: Customs invoice number
        customs_shipment_type:
          type: integer
          description: >
            Customs shipment type. Deprecated in favor of the
            `customs_information` object. 
              * `0` - Gift
              * `1` - Documents
              * `2` - Commercial Goods
              * `3` - Commercial Sample
              * `4` - Returned Goods
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
          nullable: true
          deprecated: true
        data:
          type: object
        date_created:
          type: string
        date_updated:
          type: string
        date_announced:
          type: string
        email:
          type: string
          description: >-
            An email address of the person this parcel is supposed to be
            delivered to.
        id:
          type: integer
        insured_value:
          type: integer
        label:
          $ref: '#/components/schemas/Label'
        name:
          type: string
        order_number:
          type: string
        shipment_uuid:
          type: string
        parcel_items:
          type: array
          items:
            $ref: '#/components/schemas/parcel-item'
        postal_code:
          type: string
        external_reference:
          type: string
          nullable: true
          description: >-
            A reference to be assigned to this parcel. Must be unique across
            parcels. This field is used to create idempotence.
        reference:
          type: string
          nullable: true
          description: >-
            A reference to be assigned to this parcel. Multiple parcels can have
            the same reference.
          default: '0'
        shipment:
          $ref: '#/components/schemas/Shipment'
        status:
          $ref: '#/components/schemas/Status'
        documents:
          type: array
          uniqueItems: true
          description: >-
            An array of documents. A parcel can contain multiple documents, for
            instance labels and a customs form. This field returns an array of
            all the available documents for this parcel.
          items:
            $ref: '#/components/schemas/Documents'
        telephone:
          type: string
        to_service_point:
          type: string
          description: An id of service point to which the shipment is going to be shipped.
        to_state:
          type: string
          description: >-
            Represents the state or province of a country. Countries that need a
            state are USA, Canada, Italy and Australia. e.g. America’s city of
            Los Angeles belongs to the California state: CA. Shipments to Italy
            need a province. e.g. Italy’s city of Rome belongs to Roma province:
            RM.
        total_insured_value:
          type: integer
        total_order_value_currency:
          type: string
        total_order_value:
          type: string
        tracking_number:
          type: string
          description: Tracking number of the shipment.
        tracking_url:
          type: string
          description: tracking url of this shipment.
        weight:
          type: string
        type:
          type: string
          description: >-
            Returns either ‘parcel’ or ‘letter’ by which you can determine the
            type of your shipment.
          enum:
            - parcel
            - letter
          deprecated: true
          nullable: true
        colli_uuid:
          type: string
        collo_nr:
          type: integer
          description: >-
            A number indicating the collo number within a shipment. For a
            non-multi-collo shipment, this value will always be 0. In a
            multi-collo shipment with 3 collos, this number will range from 0 to
            2.
        collo_count:
          type: integer
          description: >-
            A number indicating the number of collos within a shipment. For
            non-multi-collo shipments, this value will always be 1.
        is_return:
          type: boolean
          description: Indicates if the parcel correspond to a return.
        awb_tracking_number:
          type: string
          description: >-
            Deutsche Post Global Mail only. This indicates the air waybill
            number of this box of Global Mail parcels. This will be only set
            once Finalize box has been called.
          nullable: true
        box_number:
          type: integer
          description: >-
            Deutsche Post Global Mail only. This indicates the box to which this
            parcel belongs. This will be only set for Global Mail parcels.
          nullable: true
        length:
          type: string
          description: >-
            Parcel length in centimeters (will be used for volumetric weight
            calculation). Examples: “48” or “52.3”
          nullable: true
        width:
          type: string
          description: >-
            Parcel width in centimeters (will be used for volumetric weight
            calculation). Examples: “48” or “52.3”
          nullable: true
        height:
          type: string
          description: >-
            Parcel height in centimeters (will be used for volumetric weight
            calculation). Examples: “48” or “52.3”
          nullable: true
        shipping_method_checkout_name:
          type: string
          description: Shipping method name selected by buyer during the checkout
        customs_declaration:
          type: object
          deprecated: true
          description: >-
            An object with available printers that lists available links to the
            created customs declaration form. (deprecated in favour of
            documents).
        note:
          type: string
          description: >-
            This field can be used to add additional notes regarding an order.
            The notes will not be displayed on a label, but will be displayed on
            both the Packing slips & Picking lists which you can use for Pack &
            Go feature. The value will not be shared with carriers. It may be
            used for packing instructions, such as "gift" or "do not send before
            monday".
          nullable: true
        errors:
          $ref: '#/components/schemas/CarrierErrors'
      required:
        - id
    AddressDivided:
      title: Address Divided Object
      type: object
      properties:
        house_number:
          type: string
        street:
          type: string
      description: Address_divided object for a parcel
    carrier:
      type: string
      title: Carrier Code
      enum:
        - amazon
        - bol
        - bpost
        - brt
        - budbee
        - chronopost
        - cirro
        - colisprive
        - colissimo
        - correos
        - correos_express
        - ctt_express
        - dbschenker
        - delivengo
        - dhl
        - dhl_2_man_handling
        - dhl_de
        - dhl_ecommerce
        - dhl_express
        - dhl_parcel_gb
        - dhl_parcel_iberia
        - dp
        - dpd
        - dpd_at
        - dpd_fr
        - dpd_gb
        - dpd_local
        - evri_international
        - fadello
        - fairsenden
        - fedex
        - fedexcrossborder
        - fietskoeriers
        - geodis
        - glovo
        - gls_de
        - gls_es
        - gls_eu
        - gls_it
        - gls_nl
        - hermes_at
        - hermes_c2c_gb
        - hermes_de
        - hermes_gb
        - hived
        - homerr
        - hurby
        - inpost_es
        - inpost_gb
        - inpost_it
        - inpost_pl
        - lettresuivie
        - mhi
        - mondial_relay
        - mrw
        - nacex
        - paack
        - parcelforce
        - plx
        - postat
        - poste_italiane
        - poste_it_delivery
        - postnl
        - postnl_fulfilment
        - postnl_large
        - postnord
        - rjp
        - rjpv2
        - royal_mail
        - sandd
        - sendcloud
        - seur
        - skymail
        - spring
        - storeshippers
        - tipsa
        - tnt_it
        - transforce
        - trunkrs
        - ups
        - van_straaten
        - viatim
        - yodel
      description: A carrier represented by a Sendcloud code
      example: postnl
    Country:
      title: Country Object
      description: Country object for a parcel
      type: object
      properties:
        iso_2:
          type: string
        iso_3:
          type: string
        name:
          type: string
    Label:
      title: Label Object
      type: object
      description: Label object for a parcel
      properties:
        label_printer:
          type: string
        normal_printer:
          type: array
          items:
            type: string
    parcel-item:
      title: Parcel Item Object
      type: object
      description: The items of a Parcel
      properties:
        hs_code:
          type: string
          description: >-
            Harmonized System Code [Wikipedia
            Link](https://en.wikipedia.org/wiki/Harmonized_System).

            Providing a complete HS code with more characters increases the
            delivery rate.
          maxLength: 12
        weight:
          type: string
          description: Weight of a single item in kilograms.
        quantity:
          type: integer
          minimum: 1
          description: Quantity of items shipped.
        description:
          type: string
          description: Description of the item.
          maxLength: 255
        origin_country:
          type:
            - string
            - 'null'
          description: >-
            ISO-2 code of the country where the items were originally produced.
            [External
            Link](http://www.nationsonline.org/oneworld/country_code_list.htm).
        value:
          type: number
          description: Value of a single item.
          example: 10.5
        sku:
          type: string
          description: The SKU of the product.
          maxLength: 255
        product_id:
          type: string
          description: The internal ID of the product.
          maxLength: 255
        properties:
          type: object
          description: >-
            The list of properties of the product. Used as a JSON object with
            {‘key’: ‘value’}.
        item_id:
          type:
            - string
            - 'null'
          maxLength: 255
          description: External ID of the item generated by a shop system or similar.
        return_reason:
          type:
            - integer
            - 'null'
          description: >-
            The return reason identifier matching the ones provided from
            Sendcloud. Only applicable for returns.
          minimum: 1
        return_message:
          type:
            - string
            - 'null'
          description: >-
            Optional a message relating to the return. Only applicable for
            returns.
        mid_code:
          type: string
          description: >-
            Code to identify the manufacturer of the product. It is required
            when shipping to the US and is used for generating commercial
            invoice.
          maxLength: 15
          example: US1234567
        material_content:
          type: string
          description: Composition of the items. Used for commercial invoice generation.
          maxLength: 255
          example: 100% Cotton
        intended_use:
          type: string
          description: >-
            Text that identifies the Intended Use of the item. This will be used
            to classify the item based on the new ICS2 system. Used for
            commercial invoice generation.
          maxLength: 255
          example: Personal use
        dangerous_goods:
          $ref: '#/components/schemas/dangerous-goods'
        dds_reference:
          title: DDS Reference
          type:
            - string
            - 'null'
          description: >-
            The DDS (Due Diligence Statement) reference number associated with
            the item, if applicable. See EUDR system for more details.
          example: 25FIYPEK0A7573
        taric_doc_code:
          title: TARIC document code
          type:
            - string
            - 'null'
          description: >-
            TARIC document codes are specific alphanumeric codes used in EU
            customs declarations (Box 44) to identify required supporting
            documents, certificates, or conditions for a product, like health
            certificates (e.g., 3200), origin proofs (e.g., EUR.1), or special
            authorizations (e.g., C716 for due diligence) for simplified
            procedures, ensuring compliance with EU trade rules for various
            goods.
          example: Y142
      required:
        - hs_code
        - weight
        - quantity
        - description
        - value
    Shipment:
      title: Shipment Object
      type: object
      properties:
        id:
          type: integer
          description: ID of shipping method
        name:
          type: string
          description: Name of shipping method
      required:
        - id
      description: Shipping method object for a parcel
    Status:
      title: Status Object
      type: object
      properties:
        id:
          type: integer
        message:
          type: string
      description: Status object for a parcel
    Documents:
      title: Documents Object
      type: object
      properties:
        type:
          type: string
          description: The type of the document. See the list below for available types.
          enum:
            - label
            - cp71
            - cn23
            - commercial-invoice
            - cn23-default
        size:
          type: string
          description: 'The paper size of the document, you can expect: a4 and a6.'
        link:
          type: string
          description: >-
            A link to the document, which allows downloading of the document in
            PDF, PNG, and ZPL. Learn more about the
            [endpoint](/api/v2/integrations/retrieve-a-list-of-shipments).
             
            Send a GET request to
            https://panel.sendcloud.sc/api/v2/parcels/{parcelID}/documents/label
            using your parcel ID.


            You can pick the resolution in the parameters of the request. The
            default value is 203 dpi.
      description: Documents object for a parcel
    CarrierErrors:
      description: Errors object for a parcel
      type: object
      title: Carrier Errors Object
      properties:
        non_field_errors:
          type: array
          items:
            type: string
    dangerous-goods:
      title: DangerousGoods
      type: object
      description: Hazardous materials information for items.
      properties:
        chemical_record_identifier:
          type: string
          nullable: true
          description: Chemical record identifier for the dangerous goods
        regulation_set:
          type: string
          enum:
            - IATA
            - ADR
          description: Regulation set governing the dangerous goods
        packaging_type_quantity:
          type: string
          nullable: true
          description: Quantity of packaging type
        packaging_type:
          type: string
          nullable: true
          description: Type of packaging used
        packaging_instruction_code:
          type: string
          nullable: true
          description: Packaging instruction code
        id_number:
          type: string
          nullable: true
          description: UN identification number
        class_division_number:
          type: string
          nullable: true
          description: Hazard class and division number
        quantity:
          type: string
          nullable: true
          description: Quantity of dangerous goods
        unit_of_measurement:
          type: string
          enum:
            - KG
            - G
            - L
            - ML
          description: Unit of measurement for dangerous goods quantity
        proper_shipping_name:
          type: string
          nullable: true
          description: Proper shipping name as defined by regulations
        commodity_regulated_level_code:
          type: string
          enum:
            - LQ
            - EQ
          description: Commodity regulated level code
        transportation_mode:
          type: string
          enum:
            - Highway
            - Ground
            - PAX
            - CAO
          description: Mode of transportation
        emergency_contact_name:
          type: string
          nullable: true
          description: Name of emergency contact person
        emergency_contact_phone:
          type: string
          nullable: true
          description: Phone number of emergency contact
        adr_packing_group_letter:
          type: string
          enum:
            - I
            - II
            - III
          description: ADR packing group classification
        local_proper_shipping_name:
          type: string
          nullable: true
          description: Local proper shipping name
        transport_category:
          type: string
          nullable: true
          description: Transport category for ADR regulations
        tunnel_restriction_code:
          type: string
          nullable: true
          description: Tunnel restriction code
        weight_type:
          type: string
          enum:
            - Net
            - Gross
          description: Type of weight measurement
  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.

````