DHL Items API

openapi: 3.2.0
info:
  title: Dhl Items API
  version: 5.7.10
  description: 'Operations tagged Items across 2 of this provider''s published API definitions: dhl-deutsche-post-international-post-parcel-germany-openapi.yml, dhl-deutsche-post-international-post-parcel-germany-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-sandbox.dhl.com/
tags:
- name: Items
paths:
  /dpi/shipping/v1/items/{itemId}:
    get:
      operationId: getItemById
      summary: Get Item
      description: You get all information about a given item.
      tags:
      - Items
      parameters:
      - name: itemId
        in: path
        description: The id of the item.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer Auth access_token together with the "Bearer" prefix is required. **Example** of the header value:"*Bearer 0UuA.....*"
        required: true
        schema:
          type: string
          default: Bearer [place  OAuth access_token here, without brackets]
      responses:
        '200':
          description: Item data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        403:
          description: User 'xxx' has no permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
        '404':
          description: No item found for the given item id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
    put:
      operationId: updateItemInOrder
      summary: Update item
      description: 'Updates the item for the specified item id.


        This operation only works for items attached to orders that are in the OPEN state. Called on items of orders in the FINALIZED state leads to an 404 error (an item with the desired attributes cannot be found). The following fields are not updatable: product, serviceLevel, destinationCountry'
      tags:
      - Items
      parameters:
      - name: itemId
        in: path
        description: The id of the item.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer Auth access_token together with the "Bearer" prefix is required. **Example** of the header value:"*Bearer 0UuA.....*"
        required: true
        schema:
          type: string
          default: Bearer [place  OAuth access_token here, without brackets]
      responses:
        200:
          description: Item data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        403:
          description: User 'xxx' has no permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
        404:
          description: No item found for the given item id. Either no items with the given id exists at all or the item (or the order where the item is linked) is not in the right state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
        500:
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Item'
        description: The item data that shall be used.
        required: true
    delete:
      operationId: deleteItem
      summary: Delete Item
      description: 'Deletes the item for the specified item id.


        This operation only works for items attached to orders that are in the OPEN state. Called on items of orders in the FINALIZED state leads to an 404 error (an item with the desired attributes cannot be found).'
      tags:
      - Items
      parameters:
      - name: itemId
        in: path
        description: The id of the item.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer Auth access_token together with the "Bearer" prefix is required. **Example** of the header value:"*Bearer 0UuA.....*"
        required: true
        schema:
          type: string
          default: Bearer [place  OAuth access_token here, without brackets]
      responses:
        200:
          description: Item successfully deleted.
        403:
          description: User 'xxx' has no permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
        404:
          description: No item found for the given item id. Either no items with the given id exists at all or the item (or the order where the item is linked) is not in the right state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
        500:
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
    servers:
    - url: https://api-sandbox.dhl.com/
  /dpi/shipping/v1/items/{itemId}/label:
    get:
      operationId: getItemLabel
      summary: Get Item Label
      description: For a given item a label is generated or retrieved from the cache and send to the requestor as a bytestream response.
      tags:
      - Items
      parameters:
      - name: itemId
        in: path
        description: The id of the item.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer Auth access_token together with the "Bearer" prefix is required. **Example** of the header value:"*Bearer 0UuA.....*"
        required: true
        schema:
          type: string
          default: Bearer [place  OAuth access_token here, without brackets]
      - name: accept
        in: header
        description: Bytestream containing the media type of the generated label.
        required: true
        schema:
          type: string
          enum:
          - application/pdf
          - application/pdf+singlepage
          - application/pdf+singlepage+6x4
          - application/zpl
          - application/zpl+6x4
          - application/zpl+rotated
          - application/zpl+rotated+6x4
          - image/png
          - image/png+6x4
      responses:
        '200':
          description: Bytestream (File) containing the item label.
          content:
            application/pdf:
              schema:
                type: string
                format: byte
            application/pdf+singlepage:
              schema:
                type: string
                format: byte
            application/pdf+singlepage+6x4:
              schema:
                type: string
                format: byte
            application/zpl:
              schema:
                type: string
                format: byte
            application/zpl+6x4:
              schema:
                type: string
                format: byte
            application/zpl+rotated:
              schema:
                type: string
                format: byte
            application/zpl+rotated+6x4:
              schema:
                type: string
                format: byte
            image/png:
              schema:
                type: string
                format: byte
            image/png+6x4:
              schema:
                type: string
                format: byte
            application/json:
              schema:
                type: string
                format: byte
        '404':
          description: No item found for the given item id.
          content:
            application/pdf:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/pdf+singlepage:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/pdf+singlepage+6x4:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/zpl:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/zpl+6x4:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/zpl+rotated:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/zpl+rotated+6x4:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            image/png:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            image/png+6x4:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
        '500':
          description: Internal error.
          content:
            application/pdf:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/pdf+singlepage:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/pdf+singlepage+6x4:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/zpl:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/zpl+6x4:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/zpl+rotated:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/zpl+rotated+6x4:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            image/png:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            image/png+6x4:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
            application/json:
              schema:
                $ref: '#/components/schemas/CwsErrorDTO'
    servers:
    - url: https://api-sandbox.dhl.com/
components:
  schemas:
    Content:
      properties:
        contentPieceAmount:
          description: Number of pieces.
          example: 2
          format: int64
          maximum: 999
          minimum: 1
          type: integer
        contentPieceDescription:
          description: The (short) description of this content.
          example: Trousers
          maxLength: 33
          minLength: 3
          pattern: ^(?![=\-\+@]).*
          type: string
        contentPieceHsCode:
          description: 'The HS code of this content. Only 6, 8 or 10 digits, with at most one leading zero.

            HS Code mandatory for all shipments requiring a CN22 customs declaration.'
          example: 1234567890
          type: string
          pattern: ^([0-9]{6}|[0-9]{8}|[0-9]{10})$
        contentPieceIndexNumber:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          format: int64
          type: integer
        contentPieceNetweight:
          description: The net weight of all pieces of this content type.
          example: 1200
          format: int32
          maximum: 2000
          minimum: 1
          type: integer
        contentPieceOrigin:
          description: Country of origin, based on ISO-3166-1.
          example: DE
          maxLength: 2
          minLength: 2
          pattern: ^(?![=\-\+@]).*
          type: string
        contentPieceValue:
          description: Overall value of the content pieces of one type. 1 to 4 digits before the decimal point, 2 digits after the decimal point or 1 to 7 digits without decimal point
          example: '120.50'
          pattern: ^(?:(?:\d{1,4}\.\d{2})|(?:\d{1,7}))$
          type: string
      required:
      - contentPieceAmount
      - contentPieceDescription
      - contentPieceNetweight
      - contentPieceOrigin
      - contentPieceValue
      - item
      example:
        contentPieceHsCode: 1234567890
        contentPieceDescription: Trousers
        contentPieceValue: '120.50'
        contentPieceNetweight: 1200
        contentPieceOrigin: DE
        contentPieceAmount: 2
    CwsErrorDTO:
      type: object
      properties:
        correlationId:
          type: string
          description: The Correlation ID to track the request through all systems where it has been processed.
          example: b011a094-fade-11e7-8c3f-9a214cf093ae
        messages:
          maxItems: 2147483647
          minItems: 1
          type: array
          description: A list of messages. Any single error is described within a certain message.
          items:
            type: string
            description: A list of messages. Any single error is described within a certain message.
    Item:
      properties:
        addressLine1:
          description: 'First line of address information of the recipient.

            No unicode replacement characters � or question mark is accepted.'
          example: Any Street 100
          maxLength: 40
          minLength: 1
          pattern: ^(?![=\-\+@])[^?�]*$
          type: string
        addressLine2:
          description: 'Second line of address information of the recipient.

            No unicode replacement characters � or question mark is accepted.'
          example: Flat 2
          maxLength: 40
          minLength: 0
          pattern: ^(?![=\-\+@])[^?�]*$
          type: string
        addressLine3:
          description: 'Third line of address information of the recipient.

            No unicode replacement characters � or question mark is accepted.'
          example: 1st floor
          maxLength: 40
          minLength: 0
          pattern: ^(?![=\-\+@])[^?�]*$
          type: string
        barcode:
          description: The barcode of this item (if available).
          example: BC123456789
          readOnly: true
          type: string
        city:
          description: 'City of the recipient address.

            No unicode replacement characters � or question mark is accepted.'
          example: Any City
          maxLength: 30
          minLength: 1
          pattern: ^(?![=\-\+@])[^?�]*$
          type: string
        contents:
          description: The descriptions of the content pieces.
          items:
            $ref: '#/components/schemas/Content'
          type: array
        custRef:
          description: Reference to the customer.
          example: REF-2361890-AB
          maxLength: 28
          minLength: 0
          pattern: ^(?![=\-\+@]).*
          type: string
        custRef2:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          maxLength: 28
          minLength: 0
          type: string
        custRef3:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          maxLength: 28
          minLength: 0
          type: string
        destinationCountry:
          description: Destination country of the item, based on ISO-3166-1. Please check https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for further details.
          pattern: '[A-Z]{2}'
          maxLength: 2
          minLength: 2
          example: DE
          type: string
        id:
          description: The id of the item
          example: 1
          format: int64
          readOnly: true
          type: integer
        postalCode:
          description: 'Postal code of the recipient address. Consists of numbers, upper case letters, and one space or dash between characters

            No unicode replacement characters � or question mark is accepted.'
          example: 794
          maxLength: 10
          minLength: 3
          pattern: ^(?![=\-\+@])[^?�]*$
          type: string
        product:
          description: 'The product that is used for the shipment of this item. Available products are: GMP [Packet Priority/Prio (goods)], GPT [Packet Tracked/Tracked], GMM [Business Mail Priority/Prio (documents)], GMR [Business Mail Registered/Plus (documents)]'
          example: GMP
          type: string
        importerTaxId:
          description: Customs reference number of the recipient, if required and applicable e.g. EORI number.
          maxLength: 35
          minLength: 0
          example: 'EORI: LU12345'
          type: string
        recipient:
          description: 'Name of the recipient.

            No unicodereplacement characters � and max. one question mark is accepted.'
          example: John Doe
          maxLength: 35
          minLength: 1
          pattern: ^(?![=\-\+@])[^?�]*\??[^?�]*$
          type: string
        recipientEmail:
          description: 'Email address of the recipient. Used for notification.

            recipientEmail OR recipientPhone required for interconnect countries!


            An e-mail address or phone number for the recipient must be provided. Many postal operators have implemented electronic pick-up notifications by e-mail or SMS and the provision of this information is essential to ensure the smooth delivery of your shipments.'
          example: john.doe@example.eu
          maxLength: 50
          minLength: 0
          type: string
        recipientFax:
          description: Fax number of the recipient
          example: '+44123456789'
          maxLength: 15
          minLength: 0
          type: string
        recipientPhone:
          description: 'Phone number of the recipient.

            recipientEmail OR recipientPhone required for interconnect countries!


            An e-mail address or phone number for the recipient must be provided. Many postal operators have implemented electronic pick-up notifications by e-mail or SMS and the provision of this information is essential to ensure the smooth delivery of your shipments.'
          example: '+441234567890'
          maxLength: 25
          minLength: 0
          type: string
        returnItemWanted:
          default: false
          description: Is Packet Return.
          example: false
          type: boolean
        pDDP:
          default: false
          description: Is Item pddp? FOR FUTURE USE. Not yet relvant
          example: false
          type: boolean
        senderAddressLine1:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          maxLength: 40
          minLength: 0
          type: string
        senderAddressLine2:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          maxLength: 40
          minLength: 0
          type: string
        senderCity:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          maxLength: 40
          minLength: 0
          type: string
        senderCountry:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          maxLength: 2
          minLength: 2
          type: string
        senderEmail:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          maxLength: 50
          minLength: 0
          type: string
        senderName:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          maxLength: 40
          minLength: 0
          type: string
        senderPhone:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          maxLength: 25
          minLength: 0
          type: string
        senderPostalCode:
          description: NOT RECOMMENDED, obsolete and should not be contained in requests until further notice.
          maxLength: 20
          minLength: 0
          type: string
        senderTaxId:
          description: Customs reference number of the sender, if applicable e.g. IOSS or VOEC number.
          maxLength: 35
          minLength: 0
          example: 'IOSS: ABC12345'
          type: string
        serviceLevel:
          description: 'The service level that is used for the shipment of this item. There are restrictions for use of service level: Registered is only available with product GMR and SalesChannel DPI'
          enum:
          - PRIORITY
          - REGISTERED
          example: PRIORITY
          type: string
        shipmentAmount:
          description: Overall value of all content pieces of the item.
          example: '100.00'
          format: double
          type: number
        shipmentCurrency:
          description: Currency code of the value, based on ISO-4217. Please check https://en.wikipedia.org/wiki/ISO_4217#Active_codes for further details.
          example: EUR
          type: string
        shipmentGrossWeight:
          description: Gross weight of the item (in g). May not exceed 2000 g.
          example: 1500
          format: int32
          maximum: 2000
          minimum: 1
          type: integer
        shipmentNaturetype:
          description: 'Nature of the pieces in this item. Mandatory for non-EU shipments: SALE_GOODS, RETURN_GOODS, COMMERCIAL_SAMPLE, DOCUMENTS, MIXED_CONTENTS, OTHERS. Mandatory for non-EU shipments.'
          enum:
          - SALE_GOODS
          - RETURN_GOODS
          - COMMERCIAL_SAMPLE
          - DOCUMENTS
          - MIXED_CONTENTS
          - OTHERS
          example: SALE_GOODS
          type: string
        state:
          description: 'State of the recipient address.

            No unicode replacement characters � or question mark is accepted.

            An empty string is still allowed'
          example: NC
          maxLength: 20
          minLength: 2
          pattern: ^(?![=\-\+@])(?:$|[^?�]{2,20}$)
          type: string
        thirdPartyVendorId:
          description: The ID of the 3PV/Third Party Vendor who created this item.
          type: string
        format:
          type: string
          example: P|G|E
          description: 'The format. Weight limits are P: 100g, G: 500g, E: 2000g'
          pattern: P|G|E
      required:
      - addressLine1
      - city
      - destinationCountry
      - product
      - serviceLevel
      - recipient
      - shipmentGrossWeight
      type: object
      example:
        product: GPT
        serviceLevel: PRIORITY
        recipient: Doris Bronson
        addressLine1: Uptown street 10
        addressLine2: 2nd floor
        postalCode: SW1A 2AA
        city: London
        destinationCountry: GB
        custRef: BRE-2021-XIT
        recipientPhone: '+441234567890'
        recipientEmail: doris@somewhere.non.eu
        senderTaxId: IOSS number
        importerTaxId: IOSS number
        shipmentAmount: 100
        shipmentCurrency: EUR
        shipmentGrossWeight: 1500
        returnItemWanted: false
        shipmentNaturetype: SALE_GOODS
        contents:
        - contentPieceHsCode: 1234567890
          contentPieceDescription: Hairspray
          contentPieceValue: '120.50'
          contentPieceNetweight: 1200
          contentPieceOrigin: DE
          contentPieceAmount: 2
x-refined-from:
- dhl-deutsche-post-international-post-parcel-germany-openapi.yml
- dhl-deutsche-post-international-post-parcel-germany-openapi.yml