GlobalCheckout.yaml

openapi: 3.1.0

info:
  title: Guaranteed Quote API v1
  version: "1.0"
  termsOfService: https://www.ups.com/upsdeveloperkit/assets/html/serviceAgreement.html
  description: |
    This API provides a Global Landed Cost (GLC) duty and tax rate quote for shippers.

    ## Key Business Values
    - Simplifies the International Cross Border shipping process.
   
    For more information on the Global Checkout API, please visit the <a href="https://developer.ups.com/api/reference/globalcheckout/product-info" target="_blank" rel="noopener noreferrer">Product Info</a> page.
    
    <a href="https://developer.ups.com/api/reference/globalcheckout/appendix?loc=en_US" target="_blank" rel="noopener noreferrer">Appendix</a>
    </br><p>Explore API documentation and sample applications through GitHub.</p>
    <a href="https://github.com/UPS-API" target="_blank" rel="noopener noreferrer">
      <img src="https://www.ups.com/assets/resources/webcontent/images/gitHubButton.svg" alt="Open in GitHub" style="width: 128px; height: 32px;">
    </a>
servers: 
  - url: https://wwwcie.ups.com/api/brokerage/{version}
    description: UPS Customer Integration Environment
    variables:
      version:
        default: v1
        enum:
        - v1
  - url: https://onlinetools.ups.com/api/brokerage/{version}
    description: UPS Production
    variables:
      version:
        default: v1
        enum:
        - v1
tags: 
  - name: Global Checkout
    description: Operations related to guaranteed rate quotes
security: 
  - OAuth2: []
paths:
  /content/glc/request-quote:
    post:
      operationId: createGuaranteedQuote
      summary: returns a guaranteed landed cost quote
      description: This endpoint requests guaranteed quotes for landed cost duties and taxes.
      security:
        - OAuth2: [] 
      tags: 
        -  Global Checkout
      parameters: 
        - $ref: "#/components/parameters/transId"
        - $ref: "#/components/parameters/transactionSrc"
        - $ref: "#/components/parameters/Accept"
        - $ref: "#/components/parameters/Content-Type"
        - $ref: "#/components/parameters/registration-id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BSIS_v1_QuoteRequest'
            example:
              buyerCurrencyCode: USD
              shipperCurrencyCode: CAD
              serviceLevelCode: "01"
              referenceNumber: mar20240502
              shipperAccountNumber: " "
              shipment:
                importCountryCode: US
                importProvince: AB
                shipDate: 2024-04-01
                exportCountryCode: CA
                transModes: INT_AIR
                transportCost:
                  value: 999
                  currencyCode: USD
                insuranceCost:
                  value: 3000
                  currencyCode: USD
                shipmentType: Sale
                shipperAddress:
                  name: IKEA Edmonton
                  addressLine1: 311 102 St
                  addressLine2: NW
                  postalCode: AB T6N 1M
                  city: Edmonton
                  countryCode: AB
                  stateProvinceCode: ON
                shipToAddress:
                  name: UPS
                  addressLine1: 55 Glenlake Pkwy
                  addressLine2: NE
                  postalCode: "30328"
                  city: Sandy Springs
                  countryCode: US
                  stateProvinceCode: GA
                  residentialAddressIndicator: false
                shipmentItems:
                  - partNumber: 40093ADA2
                    quantity:
                      value: 12
                      unitOfMeasure: pallets
                    grossWeight: 
                      value: 1250
                      unitOfMeasure: kg
                    unitPrice:
                      value: 1999
                      currencyCode: USD
                    originCountryCode: GB
                    description: Surcoil Hose - Flush End - Long
                    dimension:
                      length: 48
                      width: 48
                      height: 60
                      unitOfMeasure: IN
                  - partNumber: AF4535635
                    originCountryCode: GB
                    quantity:
                      value: 10
                      unitOfMeasure: barrels
                    grossWeight:
                      value: 1500
                      unitOfMeasure: lb
                    unitPrice:
                      value: 1000
                      currencyCode: USD
                    description: Cord 5mm PK50 Yellow/Red
                    dimension:
                      length: 24
                      width: 24
                      height: 36
                      unitOfMeasure: IN
      responses:
        '200':
          description: Request successful
          headers:
            application/json:
              schema:
                $ref: '#/components/schemas/BSIS_v1_SuccessResponseHeaders'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BSIS_v1_QuoteResponse"
              example:
                quoteId: QUOTE1233445
                quoteCreationTimestamp: 2024-05-08T17:02:43+0000
                referenceNumber: aaaaaaaaaaaaaaa33
                quoteExpirationDate: 2024-05-08
                gcTotal:
                  - type: Shipper
                    value: 89.2
                    currencyCode: USD
                  - type: Buyer
                    value: 100.2
                    currencyCode: CAD
        "400":
          description: Bad Request
          headers:
            application/json:
              schema:
                $ref: "#/components/schemas/BSIS_v1_ErrorResponseHeaders"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BSIS_v1_ErrorResponse"
              example:
                response:
                  errors:
                    - code: "0061"
                      message: Required parameter registration-id is invalid.
        "401":
          description: Unauthorized
          headers:
            application/json:
              schema:
                $ref: "#/components/schemas/BSIS_v1_ErrorResponseHeaders"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BSIS_v1_ErrorResponse"
              example:
                response:
                  errors:
                    - code: UJ0001
                      message: The token was invalid/expired or could not be verified
        "422":
          description: Unprocessable Entity
          headers:
            application/json:
              schema:
                $ref: "#/components/schemas/BSIS_v1_ErrorResponseHeaders"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BSIS_v1_ErrorResponse"
              example:
                response:
                  errors:
                    - code: "105.350"
                      description: INVALID_PART_NUMBER
                      field: partNumber
                      message: PART_NUMBER is not valid
                      value: ''
components: 
  securitySchemes:
    OAuth2:
      type: oauth2
      description: |
        "Find your Client ID and Secret on your app info page. <br/> 
         1. Select \\\"Try It\\\" <br/>  
         2. In the Security section enter your Client ID and Secret.<br/> 
         3. Select \\\"Request Token\\\"<br/> 
         4. Enter any additional information in the Body and Parameters sections.<br> 
         5. Select \\\"Send\\\" to execute your API request"
      flows:
        clientCredentials:
          x-tokenEndpointAuthMethod: client_secret_basic
          tokenUrl: https://wwwcie.ups.com/security/v1/oauth/token (Opens in new window or tab)
          scopes: {}
    JWTAuth:
      type: "http"
      scheme: bearer
      bearerFormat: JWT
  parameters:
    transId:
      name: transId
      in: header
      description: An identifier unique to the request.
      required: true
      schema:
        type: string 
        example: 0a1b9c2d8e3f7g4h6i5
    transactionSrc:
      name: transactionSrc
      in: header
      description: Identifies the client/source application that is calling.
      required: true
      schema:
        type: string
        example: EWS
    Accept:
      name: Accept
      in: header
      description: The Accept request HTTP header indicates which content types, expressed as MIME types, the client is able to understand.
      required: true
      schema:
        type: string
        example: application/json
    Content-Type:
      name: Content-Type
      in: header
      description: The Content-Type header provides the client with the actual content/media type of the returned content.
      required: true
      schema:
        type: string
        example: application/json
    registration-id:
      name: registration-id
      in: header
      description: The Customer Registration Identifier used to validate the shipper account.  If not passed then it will be obtained with the OAuth token's UUID.
      required: false
      schema:
        type: string
        pattern: '^[0-9a-fA-F]{8}[-]?([0-9a-fA-F]{4}[-]?){3}[0-9a-fA-F]{12}$'
        example: "643F7EAC-DC06-19E3-84C9-0274164A04E9"
  schemas: 
    BSIS_v1_QuoteRequest:
      type: object
      required:
        - shipperAccountNumber
        - shipperCurrencyCode
        - shipment
      properties:
        buyerCurrencyCode:
          type: string
          description: | 
            Buyer's currency code adhering to ISO 4217 standard.
            Click <a href="https://developer.ups.com/api/reference/globalcheckout/appendix?loc=en_US" target="_blank" rel="noopener noreferrer">here</a> for more information.
          minLength: 3
          maxLength: 3
          pattern: ^[A-Z]{3}$
          example: USD
        shipperCurrencyCode:
          type: string
          description: | 
            Shipper's currency code adhering to ISO 4217 standard.
            Click <a href="https://developer.ups.com/api/reference/globalcheckout/appendix?loc=en_US" target="_blank" rel="noopener noreferrer">here</a> for more information.
          minLength: 3
          maxLength: 3
          pattern: ^[A-Z]{3}$
          example: USD
        serviceLevelCode:
          type: string
          description: | 
            The code for the UPS Service associated with the shipment.
            Click <a href="https://developer.ups.com/api/reference/globalcheckout/appendix?loc=en_US" target="_blank" rel="noopener noreferrer">here</a> for more information.
          enum: ["01", "02", "03", "07", "08", "11", "12", "13", "17", "54", "65", "M2", "M3", "M4", "M5", "M6", "M7", "71", "72", "74", "75", "82", "83", "84", "85", "86", "96"]
          example: '01'
        referenceNumber:
          type: string
          maxLength: 512
          description: A unique identifier used by clients for internal tracking.
          example: Refc123
        shipperAccountNumber:
          type: string
          description: The Shipper's UPS Account Number.
          minLength: 6
          maxLength: 6
          example: Acc123
        shipment:
          $ref: "#/components/schemas/BSIS_v1_Shipment"
      additionalProperties: false
    BSIS_v1_Shipment:
      type: object
      required:
        - importCountryCode
        - exportCountryCode
        - shipperAddress
        - shipToAddress
        - shipmentItems
      minItems: 1
      maxItems: 1
      properties:
        importCountryCode:
          type: string
          description: | 
            The ISO 3166 code of the country imported from.
            Click <a href="https://developer.ups.com/api/reference/globalcheckout/appendix?loc=en_US" target="_blank" rel="noopener noreferrer">here</a> for more information.
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
          example: US
        importProvince:
          type: string
          description: |
            Specifies the Province taken from.
            Click <a href="https://developer.ups.com/api/reference/globalcheckout/appendix?loc=en_US" target="_blank" rel="noopener noreferrer">here</a> for more information.
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z0-9]{2}$
          example: A0
        shipDate:
          type: string
          description: ShipDate of the Request (YYYY-MM-DD).
          format: date
          minLength: 10
          maxLength: 10
          pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$
          example: 2024-05-08
        exportCountryCode:
          type: string
          description: The ISO 3166 code of the country exported to.
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
          example: AU
        transModes:
          type: string
          description: |
            The shipment mode of transportation. If not one of the listed values then it will default to the first one from the import country.

            | Mode      | Description                                   |
            | :--:      | :--                                           |
            | DOM_AIR   | Domestic Air transportation                   |
            | DOM_OCEAN | Domestic Ocean transportation                 |
            | DOM_RAIL  | Domestic Rail transportation                  |
            | DOM_TRUCK | Domestic Truck transportation                 |
            | INT_AIR   | International Air transportation              |
            | INT_OCEAN | International Ocean transportation            |
            | INT_RAIL  | International Rail transportation             |
            | INT_TRUCK | International/Interstate Truck transportation |
          enum: [DOM_AIR, DOM_OCEAN, DOM_RAIL, DOM_TRUCK, INT_AIR, INT_OCEAN, INT_RAIL, INT_TRUCK]
          example: INT_AIR
        transportCost:
          description: |
            Specifies the Transport Costs, which are used for tariff calculations in some governments. 
            If needed and not provided then internal Rate call will be made to retrieve it.
          $ref: "#/components/schemas/BSIS_v1_ChargeDetail"
        insuranceCost:
          description: | 
            Specifies the fee charged by UPS for insuring the package, which could be used for tariff calculations in some governments.
            This will be defaulted to 0 if needed and not provided.
          $ref: "#/components/schemas/BSIS_v1_ChargeDetail"
        shipmentType:
          type: string
          description: | 
            Specifies the shipment type.

            | Type  | Description                                                       |
            | :--:  | :--                                                               |
            | GIFT  | GIFT                                                              | 
            | COMM  | Sale, Sample, Repair                                              |
            | OTHR  | Return, Other, and Intercompany Data, Anything else not supported |
            | PERS  | Personal                                                          |
          example: COMM
        shipperAddress:
          description: Shipper Address of request. Needed for internal rate call to calculate transportCost if that is needed and not provided.
          $ref: "#/components/schemas/BSIS_v1_Address"
        shipToAddress:
          description: ShipTo Address of request. Needed for internal rate call to calculate transportCost if that is needed and not provided.
          allOf:
            - $ref: "#/components/schemas/BSIS_v1_Address"
            - properties:
                residentialAddressIndicator:
                  type: boolean
                  description: | 
                    Indicate as true if the shipTo address is classified as residential (vs. commercial). Valid only for US50 addresses.
                    Needed for internal rate call to calculate transportCost if that is needed and not provided.
                  enum: [true,false]
                  example: true
        shipmentItems:
          type: array
          minItems: 1
          maxItems: 99
          description: array of request ShipmentItems.
          items:
            $ref: "#/components/schemas/BSIS_v1_ShipmentItemRequest"
      additionalProperties: false    
    BSIS_v1_ShipmentItemRequest:
      type: object
      description: Object containing the details of each item in the shipment.
      required:
        - unitPrice
        - quantity
        - partNumber
        - originCountryCode
      properties:
        grossWeight:
          description: |
            Specifies the gross weight of the entire ShipmentItem, that is, the weight of all contained Products plus the Packaging weight, if any. Specifying this value overrides
            any weight value in Product and/or Packaging objects.
          properties:
            value:
              type: integer
              description: |
                The weight value. If this field is specified, the unitOfMeasure field must also be specified.  If this field is not specified,
                unitOfMeasure must be not be set to anything but null.
              example: 4
            unitOfMeasure:
              type: string
              description: Unit Of Measure for the package weight.
              enum: [kg, lb, oz, KG, LB, OZ]
              example: lb
        unitPrice:
          $ref: "#/components/schemas/BSIS_v1_ChargeDetail"
        quantity:
          description: Container to quantity information on items within the shipmentItem.
          required:
            - value
            - unitOfMeasure
          properties:
            value:
              type: integer
              description: Item count.
              example: 4
            unitOfMeasure:
              type: string
              description: | 
                Item count Unit Of Measure
                Click <a href="https://developer.ups.com/api/reference/globalcheckout/appendix?loc=en_US" target="_blank" rel="noopener noreferrer">here</a> for more information.
              examples:
                - Case
                - Pallet
        partNumber:
          type: string
          description: Part number or SKU, pre-approved for Garanteed Landed Cost service to identifier the item being shipped.
          maxLength: 35
          example: ABDAD23455
        description:
          type: string
          description: This field is populated with the hscode description.
          maxLength: 150
          example: FABRIC FOR UPHOLSTERY
        originCountryCode:
          type: string
          description: The ISO 3166 code of the shipment item country.
          minLength: 2
          maxLength: 2
          pattern: ^[a-zA-Z0-9]{2}$
        dimension:
          type: object
          required:
            - length
            - width
            - height
            - unitOfMeasure
          properties:
            length:
              type: number
              description: package length (no limit).
              format: decimal
              example: 1
            width:
              type: number
              description: package width (no limit).
              format: decimal
              example: 2
            height:
              type: number
              description: package height (no limit).
              format: decimal
              example: 3
            unitOfMeasure:
              type: string
              description: Specifies the units of measure.
              enum: [in, cm, IN, CM]
              example: IN
      additionalProperties: false
    BSIS_v1_QuoteResponse:
      type: object
      required:
        - quoteId
        - quoteCreationTimestamp
        - quoteExpirationDate
        - gcTotal
      properties:
        quoteId:
          type: string
          description: unique quote id.
          maxLength: 32
          example: 1d2523754bde48bc95b738224de49d7b
        quoteCreationTimestamp:
          type: string
          description: Timestamp for quote generation(UTC).
          format: datetime
          minLength: 24
          maxLength: 24
          pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01]\d|2[0-3]):([0-5]\d):([0-5]\d)\+\d{4}$
          example: 2024-05-08T17:02:43+0000
        referenceNumber:
          type: string
          description: A reference for customer internal tracking from the request .
          maxLength: 512
          example: "1234567890"
        quoteExpirationDate:
          type: string
          description: Date after which the quote is no longer valid. yyyy-mm-dd format.
          format: date
          minLength: 10
          maxLength: 10
          pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$
          example: 2024-05-08
        gcTotal:
          type: array
          description: array for buyer and billing Global checkout total items.
          minItems: 1
          maxItems: 2
          items:
            $ref: "#/components/schemas/BSIS_v1_TotalResponse"
        additionalProperties: false
    BSIS_v1_TotalResponse:
      description: buyer or billing Global checkout details.
      allOf:
        - $ref: "#/components/schemas/BSIS_v1_ChargeDetail"
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              description: Shipper is mandatory and the Buyer will be conditionally returned if Buyer currency is porvided.
              enum: [Shipper, Buyer]
              example: Shipper
    BSIS_v1_ChargeDetail:
      type: object
      required:
        - value
        - currencyCode
      properties:
        value:
          type: number
          description:  The value of a particular item in the shipment .
          maxLength: 15
          format: double
          pattern: ^-?\d+(,\d{3})*(\.\d{1,2})?$
          examples:
            - 100.99
            - 999999999999.99
        currencyCode:
          type: string
          description: | 
            Currency Code of the unit total value adhering to ISO 4217 standard.
            Click <a href="https://developer.ups.com/api/reference/globalcheckout/appendix?loc=en_US" target="_blank" rel="noopener noreferrer">here</a> for more information.
          minLength: 3
          maxLength: 3
          pattern: ^[A-Z]{3}$
    BSIS_v1_Address:
      type: object
      description: Common address fields
      required:
        - addressLine1
        - countryCode
      properties:
        name:
          type: string
          description: Shipper or or Consignee's name.
          maxLength: 35
          example: John Lee
        addressLine1:
          type: string
          description: Shipper or or Consignee's street addres line 1.
          maxLength: 35
          example: 100 main street
        addressLine2:
          type: string
          description: Shipper or or Consignee's street addres line 2.
          maxLength: 35
          example: Suite 101
        postalCode:
          type: string
          description: Shipper's or Consignee's postal code.
          minLength: 5
          maxLength: 9
          pattern: ^[a-zA-Z0-9\-\s]{5,9}$
          examples:
            - '29003'
            - '300054616'
        city:
          type: string
          description: Shipper or Consignee's city.
          maxLength: 30
          example: Columbia
        countryCode:
          type: string
          description: The ISO 3166 code of the Shipper or Consignee's country or territory.
          maxLength: 2
          example: US
        stateProvinceCode:
          type: string
          description: Shipper or Consignee's state or province code.
          maxLength: 2
          example: SC
    BSIS_v1_SuccessResponseHeaders:
      description: The headers that are returned for all error responses.
      type: object
      required:
        - BkndTransId
        - transId
        - transactionSrc
        - Accept
        - Content-Type
      properties:
        BkndTransId:
          type: string
          description: The backend transaction id.
          example: UJ0001
        transId:
          type: string 
          description: An identifier unique to the request.
          example: 0a1b9c2d8e3f7g4h6i5
        transactionSrc:
          type: string
          description: Identifies the client/source application that is calling.
          example: CPC
        Accept:
          type: string
          description: The Accept request HTTP header indicates which content types, expressed as MIME types, the client is able to understand.
          example: application/json
        Content-Type:
          type: string
          description: The Content-Type header provides the client with the actual content/media type of the returned content.
          example: application/json
    BSIS_v1_ErrorResponseHeaders:
      description: The headers that are returned in error conditions
      allOf:
        - $ref: "#/components/schemas/BSIS_v1_SuccessResponseHeaders"
        - type: object
          required:
            - APIErrorCode
            - APIErrorMsg
          properties:
            APIErrorCode:
              type: string
              description: The API error code.
              example: UJ0001
            APIErrorMsg:
              type: string
              description: The API error message.
              example: Invalid token or token is not present.
    BSIS_v1_ErrorResponse:
      type: object
      description: response container.
      required: 
        - response
      properties:
        response:
          type: object
          description: errors container.
          required: 
            - errors
          properties:
            errors:
              type: array
              description: error payload - array containing one or more Errors.
              items:
                $ref: '#/components/schemas/BSIS_v1_Error'
      additionalProperties: false
    BSIS_v1_Error:
      type: object
      description: container for error and warning messages
      required:
        - code
        - message
      properties:
        code:
          description: code for the given message
          type: string
          example: "105.300"
        description:
          type: string
          description: Internal description of the error
          example: VALUE_REQUIRED
        message:
          description: the warning or error message to be conveyed
          type: string
          maxLength: 200
          example: Required field 'ImportCountryCode' is null.
        value:
          type: string
          description: The value that caused the error
          example: ''
        field:
          type: string
          description: The path to the field causing the error as returned from the backend services.
          example: shipment.importCountryCode