openapi: 3.0.0
info:
  title: DHL eCommerce Americas Product Finder API
  version: 4.0.0
  description: |
    DHL eCommerce Americas Product Finder API enables clients to determine which DHL shipping products are suitable for a given shipping request including associated rates and estimated delivery dates (EDD). The rates returned are account-specific along with a list of applicable surcharges (if any).
    
    The DHL Product Finder API covers all DHL eCommerce Americas shipping products - both Domestic and International.

servers:
  - url: https://api-dev.dhlecs.com/shipping/v4
    description: Sandbox server for testing

paths:
  "/products":
    post:
      tags:
        - Product Finder
      operationId: createShippingProduct
      summary: "Find Products and Rates"
      description: |
        Provide a single package data to get possible products, and optionally obtain rates and EDD.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pickup:
                  type: string
                  maxLength: 10
                  minLength: 4
                  pattern: '^[\S]+$'
                  description: DHLeCS pickup account number. You will receive this after doing the onboarding with DHL sales
                  example: "5320037"
                orderedProductId:
                  type: string
                  maxLength: 3
                  minLength: 3
                  pattern: '^[A-Z]{3}$'
                  description: DHLeCS three-character product code. Please refer to our documentation site for a list of valid values
                  example: "PLT"
                distributionCenter:
                  maxLength: 6
                  minLength: 6
                  pattern: '^[\S]+$'
                  type: string
                  description: Primary DHLeCS Distribution center assigned to your products/services
                  example: "USLAX1"
                consigneeAddress:
                  type: object
                  required:
                    - address1
                    - city
                    - country
                  properties:
                    name:
                      maxLength: 50
                      minLength: 0
                      pattern: '^$|.*[^\s].*'
                      type: string
                      description: Name of consignee.
                      example: John Doe
                    companyName:
                      maxLength: 30
                      minLength: 0
                      pattern: '^$|.*[^\s].*'
                      type: string
                      description: Company name of consignee.
                      example: Doe Inc.
                    address1:
                      maxLength: 50
                      minLength: 1
                      pattern: '^$|.*[^\s].*'
                      type: string
                      description: Address line 1 of consignee.
                      example: 5923 Peachtree Industrial Blvd
                    address2:
                      maxLength: 50
                      minLength: 0
                      type: string
                      description: Address line 2 of consignee.
                      example: Suite 100 
                    city:
                      maxLength: 40
                      minLength: 1
                      pattern: '^$|.*[^\s].*'
                      type: string
                      description: City of consignee.
                      example: Norcross
                    state:
                      maxLength: 50
                      minLength: 0
                      type: string
                      description: State of consignee.
                      example: ON
                    country:
                      maxLength: 2
                      minLength: 2
                      pattern: '^[A-Z]{2}$'
                      type: string
                      description: Two-character ISO consignee address country code.
                      example: MX
                    postalCode:
                      maxLength: 10
                      minLength: 3
                      type: string
                      description: Postal code of consignee.
                      example: 30024
                    email:
                      maxLength: 50
                      minLength: 0
                      type: string
                      description: E-mail address of consignee.
                      example: 2@y.com
                    phone:
                      maxLength: 26
                      minLength: 0
                      type: string
                      description: Phone number of consignee.
                      example: 44423440348
                returnAddress:
                  type: object
                  required:
                    - address1
                    - city
                    - country
                  properties:
                    name:
                      maxLength: 50
                      minLength: 0
                      pattern: '^$|.*[^\s].*'
                      type: string
                      description: Name of return address.
                      example: Dave Bloggs
                    companyName:
                      maxLength: 30
                      minLength: 0
                      pattern: '^$|.*[^\s].*'
                      type: string
                      description: Company name of return address.
                      example: Joe Inc.
                    address1:
                      maxLength: 50
                      minLength: 1
                      pattern: '^$|.*[^\s].*'
                      type: string
                      description: Address line 1 of return address.
                      example: 4552 OLD DIXIE HWY
                    address2:
                      maxLength: 50
                      minLength: 0
                      type: string
                      description: Address line 2 of return address.
                      example: Near Pixar road
                    city:
                      maxLength: 40
                      minLength: 1
                      pattern: '^$|.*[^\s].*'
                      type: string
                      description: City of return address.
                      example: Norcross
                    state:
                      maxLength: 50
                      minLength: 0
                      type: string
                      description: State of return address.
                      example: GA
                    country:
                      maxLength: 2
                      minLength: 2
                      pattern: '^[A-Z]{2}$'
                      type: string
                      description: Two-character ISO return address country code.
                      example: US
                    postalCode:
                      maxLength: 10
                      minLength: 3
                      type: string
                      description: Postal code of return address.
                      example: 30092
                    email:
                      maxLength: 50
                      minLength: 0
                      type: string
                      description: E-mail address of return address.
                      example: 2@y.com
                    phone:
                      maxLength: 26
                      minLength: 0
                      type: string
                      description: Phone number of return address.
                      example: 44423440348
                packageDetail:
                  type: object
                  properties:
                    packageId:
                      type: string
                      example: "V4-TEST-1586965592482"
                    packageDescription:
                      type: string
                      example: "Your order"
                    weight:
                      required:
                        - unitOfMeasure
                        - value
                      type: object
                      properties:
                        value:
                          type: number
                          multipleOf: 0.01
                          maximum: 999999.99
                          minimum: 0.01
                          description: Total package weight.
                          format: float
                          example: 4.2
                        unitOfMeasure:
                          type: string
                          description: Unit of measure for the weight.
                          example: LB
                          enum:
                            - LB
                            - OZ
                            - KG
                            - G
                    shippingCost:
                      required:
                        - currency
                      type: object
                      properties:
                        currency:
                          maxLength: 3
                          minLength: 3
                          description: Three-character ISO Currency code.
                          type: string
                          example: "USD"
                        freight:
                          type: number
                          format: float
                          maximum: 99999999.99
                          multipleOf: 0.01
                          minimum: 0.01
                          description: Freight charges for the package.
                          example: 10.5
                        declaredValue:
                          type: number
                          format: float
                          maximum: 99999999.99
                          multipleOf: 0.01
                          minimum: 0.01
                          description: Total declared value for the package. While not mandatory, best practice is to provide if available.
                          example: 83.6
                        insuredValue:
                          type: number
                          format: float
                          maximum: 99999999.99
                          multipleOf: 0.01
                          minimum: 0.01
                          description: Total insured value of the package.
                          example: 80
                        dutiesPaid:
                          type: boolean
                          description: If duties and taxes for the shipment are paid by the shipper. International reference DDU or DDP.
                          example: false
                    service:
                      minLength: 0
                      type: string
                      description: Shipments originating and destined to the United States will default to DELCON. Signature confirmation* is also available for certain products at an additional cost (please contact your Sales representative for more details). International shipments will default to the tracking capabilities available to the product/service selected. Shipment tracking is available for all parcel products. Tracking is available through the DHLeCS web portal, or through the USPS tracking site. For Domestic shipments DELCON, or SIGCON. Leave blank for International shipments.
                      example: DELCON
                      enum:
                        - DELCON
                        - SIGCON
                customsDetails:
                  type: array
                  items:
                    type: object
                    properties:
                      itemDescription:
                        type: string
                        example: "Board game - toys"
                      countryOfOrigin:
                        maxLength: 2
                        minLength: 2
                        pattern: '^[A-Z]{2}$'
                        type: string
                        description: Two-Character Country Code for Origin Manufacturer Country of the product.
                        example: CN
                      hsCode:
                        maxLength: 20
                        minLength: 6
                        type: string
                        description: Harmonized Tariff Schedule is a number assigned to every possible commodity that can be imported or exported from any country. Please do not include any decimals "." in this field.
                        example: '644556'
                      packagedQuantity:
                        maximum: 999999
                        minimum: 1
                        type: integer
                        description: Quantity of the same item in the package.
                        format: int32
                        example: 2
                      skuNumber:
                        maxLength: 20
                        minLength: 1
                        type: string
                        description: SKU #, or item code - Used for product verification on clients website during customs clearance process.
                        example: "123"
                      itemValue:
                        type: number
                        format: float
                        maximum: 99999999.99
                        multipleOf: 0.01
                        minimum: 0.01
                        description: Commercial value of the commodity (per each).
                        example: 34
                      currency:
                        type: string
                        example: "USD"
                rate:
                  type: object
                  properties:
                    calculate:
                      type: boolean
                      example: true
                    rateDate:
                      type: string
                      example: "2020-07-12"
                    maxPrice:
                      type: number
                      example: 30
                    currency:
                      type: string
                      example: "USD"
                estimatedDeliveryDate:
                  type: object
                  properties:
                    calculate:
                      type: boolean
                      description: Whether or not to calculate the estimated delivery date (EDD) for each product returned. EDD is not calculated by default.
                      example: true
                    expectedShipDate:
                      type: string
                      format: date
                      example: '2020-04-27'
                    expectedTransit:
                      maximum: 99
                      minimum: 1
                      type: integer
                      description: Maximum number of transit days for the shipment. Products which would take longer are not returned.
                      example: 10
                    deliveryBy:
                      type: string
                      description: Date by which the shipment should arrive at its destination. Products which would take longer are not returned.
                      format: date
                      example: '2020-07-21'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  pickup:
                    type: string
                    example: "5320037"
                  distributionCenter:
                    type: string
                    example: "USLAX1"
                  orderedProductId:
                    type: string
                    example: "PLT"
                  consigneeAddress:
                    type: object
                    properties:
                      name:
                        type: string
                        example: "John Doe"
                      companyName:
                        type: string
                        example: "Doe Inc."
                      address1:
                        type: string
                        example: "5923 Peachtree Industrial Blvd"
                      address2:
                        type: string
                        example: "Suite 100"
                      city:
                        type: string
                        example: "Norcross"
                      state:
                        type: string
                        example: "ON"
                      country:
                        type: string
                        example: "MX"
                      postalCode:
                        type: string
                        example: "30024"
                      email:
                        type: string
                        example: "2@y.com"
                  returnAddress:
                    type: object
                    properties:
                      name:
                        type: string
                        example: "Dave Bloggs"
                      companyName:
                        type: string
                        example: "Joe Inc."
                      address1:
                        type: string
                        example: "4552 OLD DIXIE HWY"
                      address2:
                        type: string
                        example: "Near Pixar road"
                      city:
                        type: string
                        example: "Norcross"
                      state:
                        type: string
                        example: "GA"
                      country:
                        type: string
                        example: "US"
                      postalCode:
                        type: string
                        example: "30092"
                      email:
                        type: string
                        example: "2@y.com"
                      phone:
                        type: string
                        example: "44423440348"
                  packageDetail:
                    type: object
                    properties:
                      packageId:
                        type: string
                        example: "V4-TEST-1594523253074"
                      packageDescription:
                        type: string
                        example: "Your order"
                      weight:
                        type: object
                        properties:
                          value:
                            type: number
                            example: 4.2
                          unitOfMeasure:
                            type: string
                            example: "LB"
                      shippingCost:
                        type: object
                        properties:
                          currency:
                            type: string
                            example: "USD"
                          freight:
                            type: number
                            example: 10.5
                          declaredValue:
                            type: number
                            example: 83.6
                          insuredValue:
                            type: number
                            example: 80
                          dutiesPaid:
                            type: boolean
                            example: false
                      service:
                        type: string
                        example: "DELCON"
                  customsDetails:
                    type: array
                    items:
                      type: object
                      properties:
                        itemDescription:
                          type: string
                          example: "Board game - toys"
                        countryOfOrigin:
                          type: string
                          example: "CN"
                        hsCode:
                          type: string
                          example: "644556"
                        packagedQuantity:
                          type: integer
                          example: 2
                        itemValue:
                          type: number
                          example: 34
                        currency:
                          type: string
                          example: "USD"
                        skuNumber:
                          type: string
                          example: "123"
                  rate:
                    type: object
                    properties:
                      calculate:
                        type: boolean
                        example: true
                      rateDate:
                        type: string
                        example: "2020-07-12"
                      maxPrice:
                        type: number
                        example: 30
                      currency:
                        type: string
                        example: "USD"
                  estimatedDeliveryDate:
                    type: object
                    properties:
                      calculate:
                        type: boolean
                        example: true
                      expectedShipDate:
                        type: string
                        example: "2020-07-12"
                      expectedTransit:
                        type: integer
                        example: 10
                      deliveryBy:
                        type: string
                        example: "2020-07-21"
                  products:
                    type: array
                    items:
                      type: object
                      properties:
                        orderedProductId:
                          type: string
                          example: "PLT"
                        productName:
                          type: string
                          example: "DHL Parcel International Direct"
                        description:
                          type: string
                          example: "Direct shipping up to 44 lbs. to 210 countries with expected delivery in 3 - 10 working days"
                        trackingAvailable:
                          type: string
                          example: "FULL"
                        rate:
                          type: object
                          properties:
                            priceZone:
                              type: string
                              example: "MX00PL"
                            amount:
                              type: number
                              example: 19.2
                            currency:
                              type: string
                              example: "USD"
                            rateComponents:
                              type: array
                              items:
                                type: object
                                properties:
                                  rateComponentId:
                                    type: string
                                    example: "ZBPT"
                                  partId:
                                    type: string
                                    example: "60"
                                  description:
                                    type: string
                                    example: "Base Rate"
                                  amount:
                                    type: number
                                    example: 18.61
                        messages:
                          type: array
                          items:
                            type: object
                            properties:
                              messageId:
                                type: string
                                example: "100"
                              messageText:
                                type: string
                                example: "Phone Number Required"
        '400':
          description: Static Validation Failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: "https://api.dhlecs.com/docs/errors/400.0604001"
                  title:
                    type: string
                    example: "Static Validation Failed"
                  invalidParams:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: "country"
                        path:
                          type: string
                          example: "/returnAddress/country"
                        reason:
                          type: string
                          example: "expected maxLength: 2, actual: 3"
        '401':
          description: No credentials provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: "https://api.dhlecs.com/docs/errors/401.0000008"
                  title:
                    type: string
                    example: "No credentials provided"


        '500':
          description: Internal Server Error
components:
  securitySchemes:
   OAuth2:
    type: oauth2
    description: This API uses OAuth 2 with the client-credentials grant flow
    flows:
      clientCredentials:
        tokenUrl: https://api-dev.dhlecs.com/auth/v4/accesstoken
        scopes: {}
 
security:
  - OAuth2: []
 