CustomsDetailV2.yaml

openapi: 3.1.0
info:
  title: Customs Detail API v2
  version: "1.0"
  description: >
   # Product Info
    Provides clients with up‑to‑date compliance requirements for data fields that must be captured for UPS shipments. The API then validates these field values and submits them for backend merging into the shipment. For more information on the Customs Detail API, please visit the <a href="https://developer.ups.com/api/reference/customsdetail/product-info"
    target="_blank" rel="noopener">Product Info</a> page.<br/><br/>

    # Key Business Values
    - Ensures clients always receive the latest compliance requirements.
    - Allows field collection to be fully managed through configurable user settings.
    - Flexible framework eliminates additional code changes as compliance fields evolve.
    - Flexible field model supports new country rules without disruptive changes, so you can expand lanes and stay current as regulations evolve.

    # Reference
    - <a href="https://developer.ups.com/api/reference/customdetails/error-codes" target="_blank" rel="noopener">Errors</a>
    - <a href="https://developer.ups.com/api/reference/customdetails/faq" target="_blank" rel="noopener">FAQ</a>
    <br/>
    <p>Try out UPS APIs with example requests using Postman and learn more about the UPS Postman Collection by visiting our <a href="https://developer.ups.com/api/reference/postman/guide"
    target="_blank" rel="noopener">Postman Guide</a>. Explore API documentation and sample applications through GitHub.</p>
    
    <a href="https://god.gw.postman.com/run-collection/29542085-f2cd7176-bd05-48ea-bb72-b359a11cff09?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D29542085-f2cd7176-bd05-48ea-bb72-b359a11cff09%26entityType%3Dcollection%26workspaceId%3D7e7595f0-4829-4f9a-aee1-75c126b9d417" target="_blank" rel="noopener noreferrer">
      <img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height: 32px;"></a>
    <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://onlinetools.ups.com/api/trade/compliance/{version}
    description: Production
    variables:
      version:
        default: v2
        enum:
          - v2
  - url: https://wwwcie.ups.com/api/trade/compliance/{version}
    description: CIE
    variables:
      version:
        default: v2
        enum:
        - v2
tags:
  - name: Customs Detail
    description:  Endpoints related to the required fields
paths:
  /content/fields/customs-detail:
    post:
      summary: Validate and/or submit the fields
      description: This endpoint will provide the ability to validate and/or submit the additional field information for a shipment
      parameters:
        - $ref: "#/components/parameters/transId"
        - $ref: "#/components/parameters/transactionSrc"
        - $ref: "#/components/parameters/Content-Type"
        - name: version
          in: path
          description: version
          required: true
          schema:
            type: string
            default: v2
            enum:
                -   v2
      operationId: postCustomDetailData
      security:
        - OAuth2: []
      tags:
        - Customs Detail
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomDetailsPostFieldsRequestv2"
            example:
              actionType: save
              shipperNumber: 1443YY
              trackingNumber: 1Z1443YY0161231327
              shipmentMetaData:
                - groupKey: US-IMP-CDC
                  fields:
                    - fieldKey: ImportLicenseNumber
                      regulationSections:
                        - sectionKey: Bio
                      fieldValue: "123412351234123"
                - groupKey: IN-EXP-CSB
                  fields:
                    - fieldKey: CSBType
                      fieldValue: "3"
                    - fieldKey: IECCode
                      fieldValue: "99"
              products:
                - productId: PART-001
                  productDescription: Medical device
                  commodityCode: "3821000010"
                  productMetaData:
                    - groupKey: IN-EXP-CSB
                      fields:
                        - fieldKey: Amount
                          fieldValue: "10"
                        - fieldKey: CurrencyCode
                          fieldValue: USD
                    - groupKey: US-IMP-FDA
                      fields:
                        - fieldKey: MnuNa
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          fieldValue: UPS Labs
                        - fieldKey: MnuAdLn1Te
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          fieldValue: "55 Glenlake Pkwy NE"
                        - fieldKey: MnuAdLn2Te
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          fieldValue: "Suite 400"
                        - fieldKey: MnuAdLn3Te
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          fieldValue: "Building C"
                        - fieldKey: MnuCtyNa
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          fieldValue: "Atlanta"
                        - fieldKey: MnuStPrvCd
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          fieldValue: "GA"
                        - fieldKey: MnuCtyCd
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          fieldValue: "US"
                        - fieldKey: MnuPslCd
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          fieldValue: "30301"
                - productId: PART-002
                  productDescription: Sample pharma goods
                  commodityCode: "300490"
                  productMetaData:
                    - groupKey: US-IMP-FDA
                      fields:
                        - fieldKey: MnuNa
                          regulationSections:
                            - sectionKey: Cos
                          fieldValue: UPS Labs
                        - fieldKey: MnuPslCd
                          regulationSections:
                            - sectionKey: Cos
                          fieldValue: "30301"
                        - fieldKey: MnuAdLn1Te
                          regulationSections:
                            - sectionKey: Cos
                          fieldValue: 55 Glenlake Pkwy NE
                        - fieldKey: MnuCtyNa
                          regulationSections:
                            - sectionKey: Cos
                          fieldValue: Atlanta
                        - fieldKey: MnuStPrvCd
                          regulationSections:
                            - sectionKey: Cos
                          fieldValue: GA
                        - fieldKey: MnuCtyCd
                          regulationSections:
                            - sectionKey: Cos
                          fieldValue: US
      responses:
        "204":
          description: Success
          headers:
            BkndTransId:
              $ref: "#/components/headers/BkndTransId"
            TransId:
              $ref: "#/components/headers/transId"
            transactionSrc:
              $ref: "#/components/headers/transactionSrc"
            Content-Type:
              $ref: "#/components/headers/Content-Type"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "422":
          $ref: '#/components/responses/UnprocessableEntity'
        "500":
          $ref: '#/components/responses/ServerError'
    get:
      summary: Returns required Custom Details
      description: This returns an array of fields that are required for the provided import and/or export country
      parameters:
        - $ref: "#/components/parameters/transId"
        - $ref: "#/components/parameters/transactionSrc"
        - $ref: "#/components/parameters/Content-Type"
        - name: import_country_code
          in: query
          required: false
          schema:
            type: 
              - string
              - "null"
            description: |
              The <a href="https://www.iso.org/iso-3166-country-codes.html" target="_blank">ISO 3166</a> country or territory code
              from where the shipment is being imported to. If this is omitted then all import fields for all countries will be returned
            minLength: 2
            maxLength: 2
            pattern: ^[A-Z]{2}$
            example: US
        - name: export_country_code
          in: query
          required: false
          schema:
            type: 
              - string
              - "null"
            description: |
              The <a href="https://www.iso.org/iso-3166-country-codes.html" target="_blank">ISO 3166</a> country or territory code
              from where the shipment is being exported from. If this is omitted then all export fields for all countries will be returned
            minLength: 2
            maxLength: 2
            pattern: ^[A-Z]{2}$
            example: IT
        - name: locale
          in: query
          required: false
          schema:
            type: string
            description: ""
            minLength: 5
            maxLength: 5
            pattern: ^[a-z]{2}-[A-Z]{2}$
            default: en-US
            example: en-US
        - name: commodity_codes
          in: query
          required: false
          description: comma-separated list of tariff code for the product for the selected import country and process type  to filter results.
          schema:
            type: 
              - string
              - "null"
            minLength: 1
            maxLength: 2000
            example: "2926400000,3003395000"
        - name: version
          in: path
          description: version
          required: true
          schema:
            type: string
            default: v2
            enum:
                -   v2
      operationId: getCustomDetailData
      security:
        - OAuth2: []
      tags:
        - Customs Detail
      responses:
          "200":
            description: Success
            headers:
              BkndTransId:
                $ref: "#/components/headers/BkndTransId"
              TransId:
                $ref: "#/components/headers/transId"
              transactionSrc:
                $ref: "#/components/headers/transactionSrc"
              Content-Type:
                $ref: "#/components/headers/Content-Type"
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/CustomDetailsGetFieldsSuccessResponsev2"
                example:
                  commodityCodes:
                    - commodityCode: "2926400000"
                      regulations:
                        - regulation: FDA
                          regulationSections:
                            - sectionKey: DRU
                    - commodityCode: "3003395000"
                      regulations:
                        - regulation: FDA
                          regulationSections:
                            - sectionKey: DRU
                  fieldGroups:
                    - countryCode: US
                      countryName: UNITED STATES OF AMERICA
                      shipmentType: Import
                      groupKey: US-IMP-FDA
                      details: This is for US import FDA fields
                      regulation: FDA
                      regulationSections:
                        - sectionKey: Cos
                          sectionName: Cosmetics
                        - sectionKey: Bio
                          sectionName: Biologics
                        - sectionKey: Dev
                          sectionName: Device
                        - sectionKey: Foo
                          sectionName: Food
                      fields:
                        - sectionKey: MnuNa
                          label: Manufacturer Name
                          order: "1"
                          tooltip: Type of shipping bill to be processed for the shipment
                          isRequired: C
                          requirementConditions:
                            - fieldKey: MnuPslCd
                              operator: "!="
                              value: ""
                          fieldType: textbox
                          allowedValueCount: 1
                          validation:
                            minLength: null
                            maxLength: null
                            errorMessage: Enter a valid value
                            dataType: Text
                            regexPattern: null
                            listValues: []
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          keyAlias: ManufacturerName
                          level: Product
                        - sectionKey: MnuPslCd
                          label: Manufacturer Postal Code
                          order: "8"
                          tooltip: The postal code address of the manufacturer for the product
                          isRequired: Y
                          requirementConditions: null
                          fieldType: textbox
                          allowedValueCount: 1
                          validation:
                            minLength: null
                            maxLength: null
                            errorMessage: Enter a valid value
                            dataType: Text
                            regexPattern: null
                            listValues: []
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          keyAlias: ManufacturerPostalCode
                          level: Product
                        - sectionKey: MnuAdLn1Te
                          label: Manufacturer Address Line 1
                          order: "1"
                          tooltip: Line 1 of the address of the manufacturer for the product
                          isRequired: N
                          requirementConditions: null
                          fieldType: textbox
                          allowedValueCount: 1
                          validation:
                            minLength: null
                            maxLength: null
                            errorMessage: Enter a valid value
                            dataType: Text
                            regexPattern: null
                            listValues: []
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          keyAlias: ManufacturerAddressLine1
                          level: Product
                        - sectionKey: MnuAdLn2Te
                          label: Manufacturer Address Line 2
                          order: "1"
                          tooltip: Line 2 of the address of the manufacturer for the product
                          isRequired: N
                          requirementConditions: null
                          fieldType: textbox
                          allowedValueCount: 1
                          validation:
                            minLength: null
                            maxLength: null
                            errorMessage: Enter a valid value
                            dataType: Text
                            regexPattern: null
                            listValues: []
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          keyAlias: ManufacturerAddressLine2
                          level: Product
                        - sectionKey: MnuAdLn3Te
                          label: Manufacturer Address Line 3
                          order: "1"
                          tooltip: Line 3 of the address of the manufacturer for the product
                          isRequired: N
                          requirementConditions: null
                          fieldType: textbox
                          allowedValueCount: 1
                          validation:
                            minLength: null
                            maxLength: null
                            errorMessage: Enter a valid value
                            dataType: Text
                            regexPattern: null
                            listValues: []
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          keyAlias: ManufacturerAddressLine3
                          level: Product
                        - sectionKey: MnuCtyNa
                          label: Manufacturer City Name
                          order: "1"
                          tooltip: Line 3 of the address of the manufacturer for the product
                          isRequired: N
                          requirementConditions: null
                          fieldType: textbox
                          allowedValueCount: 1
                          validation:
                            minLength: null
                            maxLength: null
                            errorMessage: Enter a valid value
                            dataType: Text
                            regexPattern: null
                            listValues: []
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          keyAlias: ManufacturerAddressLine3
                          level: Product
                        - sectionKey: MnuStPrvCd
                          label: Manufacturer State/Province Code
                          order: "1"
                          tooltip: The state/province for the address of the manufacturer for the product
                          isRequired: N
                          requirementConditions: null
                          fieldType: textbox
                          allowedValueCount: 1
                          validation:
                            minLength: null
                            maxLength: null
                            errorMessage: Enter a valid value
                            dataType: Text
                            regexPattern: null
                            listValues: []
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          keyAlias: ManufacturerStateProvinceCode
                          level: Product
                        - sectionKey: MnuCtyCd
                          label: Manufacturer Country Code
                          order: "1"
                          tooltip: The country code for the address of the manufacturer for the product
                          isRequired: N
                          requirementConditions: null
                          fieldType: textbox
                          allowedValueCount: 1
                          validation:
                            minLength: null
                            maxLength: null
                            errorMessage: Enter a valid value
                            dataType: Text
                            regexPattern: null
                            listValues: []
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          keyAlias: ManufacturerCountryCode
                          level: Product
                        - sectionKey: MnuPslCd
                          label: Manufacturer Postal Code
                          order: "1"
                          tooltip: The postal code address of the manufacturer for the product
                          isRequired: Y
                          requirementConditions: null
                          fieldType: textbox
                          allowedValueCount: 1
                          validation:
                            minLength: null
                            maxLength: null
                            errorMessage: Enter a valid value
                            dataType: Text
                            regexPattern: null
                            listValues: []
                          regulationSections:
                            - sectionKey: Cos
                            - sectionKey: Bio
                            - sectionKey: Dev
                            - sectionKey: Foo
                          keyAlias: ManufacturerPostalCode
                          level: Product
          "401":
            $ref: '#/components/responses/Unauthorized'
          "422":
            $ref: '#/components/responses/UnprocessableEntity'
          "500":
            $ref: '#/components/responses/ServerError'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: |
        Find your Client ID and Secret on your app info page. 
          1. Select "Try It" 
          2. In the Security section enter your Client ID and Secret 
          3. Select "Request Token"
          4. Enter any additional information in the Body and Parameters sections
          5. Select "Send" to execute your API request"
      flows:
        clientCredentials:
          x-tokenEndpointAuthMethod: client_secret_basic
          tokenUrl: https://onlinetools.ups.com/security/v2/oauth/token
          scopes: {}
    oauthCie:
      type: oauth2
      description: |
        Find your Client ID and Secret on your app info page. 
          1. Select "Try It" 
          2. In the Security section enter your Client ID and Secret 
          3. Select "Request Token"
          4. Enter any additional information in the Body and Parameters sections
          5. Select "Send" to execute your API request"
      flows:
        clientCredentials:
          x-tokenEndpointAuthMethod: client_secret_basic
          tokenUrl: https://wwwcie.ups.com/security/v2/oauth/token
          scopes: {}
    JWTAuth:
      type: "http"
      scheme: bearer
      bearerFormat: JWT
  parameters:
    transId:
      name: transId
      in: header
      required: true
      schema:
        type: string
        description: Transaction Id
    transactionSrc:
      name: transactionSrc
      in: header
      required: true
      schema:
        type: string
        description: Identifies the clients/source application that is calling
    Content-Type:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        description: accepted value application/json
  headers:
    BkndTransId:
      description: The backend transaction id.
      schema:
        type: string
        example: 383f7d397a48
    transId:
      description: An identifier unique to the request.
      schema:
        type: string 
        pattern: ^[a-zA-Z0-9-.]+$
        maxLength: 512
        example: 0a1b9c2d8e3f7g4h6i5
    transactionSrc:
      description: Identifies the client/source application that is calling.
      schema:
        type: string
        pattern: ^[a-zA-Z0-9-.]+$
        maxLength: 512
        example: UPS.com
    Content-Type:
      description: The Content-Type header provides the client with the actual content/media type of the returned content.
      schema:
        type: string
        example: application/json
    APIErrorCode:
      description: The API error code.
      schema:
        type: string
        example: UJ0001
    APIErrorMsg:
      description: The API error message.
      schema:
        type: string
        example: Invalid token or token is not present.
  responses:
    BadRequest:
      description: Bad Request
      headers:
        BkndTransId:
          $ref: "#/components/headers/BkndTransId"
        transId:
          $ref: "#/components/headers/transId"
        transactionSrc:
          $ref: "#/components/headers/transactionSrc"
        Content-Type:
          $ref: "#/components/headers/Content-Type"
        APIErrorCode:
          $ref: "#/components/headers/APIErrorCode"
        APIErrorMessage:
          $ref: "#/components/headers/APIErrorMsg"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomDetailsErrorResponsev2'
          example:
            response:
              errors:
                - code: "105.000"
                  message: Malformed JSON request
                - code: "105.004"
                  message: Field value is required
                  description: "VALUE_REQUIRED"
                  field: "shipperNumber"
                  value: null
    Unauthorized:
      description: Unauthorized
      headers:
        BkndTransId:
          $ref: "#/components/headers/BkndTransId"
        transId:
          $ref: "#/components/headers/transId"
        transactionSrc:
          $ref: "#/components/headers/transactionSrc"
        Content-Type:
          $ref: "#/components/headers/Content-Type"
        APIErrorCode:
          $ref: "#/components/headers/APIErrorCode"
        APIErrorMessage:
          $ref: "#/components/headers/APIErrorMsg"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomDetailsErrorResponsev2'
          example: 
            response:
              errors: 
                - code: "105.401"
                  message: Invalid token or token is not present
                  description: null
                  field: null
                  value: null    
    UnprocessableEntity:
      description: Unprocessable Entity
      headers:
        BkndTransId:
          $ref: "#/components/headers/BkndTransId"
        transId:
          $ref: "#/components/headers/transId"
        transactionSrc:
          $ref: "#/components/headers/transactionSrc"
        Content-Type:
          $ref: "#/components/headers/Content-Type"
        APIErrorCode:
          $ref: "#/components/headers/APIErrorCode"
        APIErrorMessage:
          $ref: "#/components/headers/APIErrorMsg"
      content:
        application/json: 
          schema: 
            $ref: "#/components/schemas/CustomDetailsErrorResponsev2"
          example:
            response:
              errors:
                - code: "105.001"
                  description: INVALID_FIELD_VALUE
                  field: importCountryCode
                  message: Supplied value was not in the correct range of valid values.
                  value: USA
    ServerError:
      description: Server Error
      headers:
        BkndTransId:
          $ref: "#/components/headers/BkndTransId"
        transId:
          $ref: "#/components/headers/transId"
        transactionSrc:
          $ref: "#/components/headers/transactionSrc"
        Content-Type:
          $ref: "#/components/headers/Content-Type"
        APIErrorCode:
          $ref: "#/components/headers/APIErrorCode"
        APIErrorMessage:
          $ref: "#/components/headers/APIErrorMsg"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomDetailsErrorResponsev2'
          example:
            response: 
              errors:
                - code: "105.500"
                  message: Internal Server Error
                  description: INTERNAL_ERROR
                  field: null
                  value: null
  schemas:
    #/content/fields/customs-detail
    CustomDetailsPostFieldsRequestv2:
      type: object
      description: Container for the posting of field data
      properties:
        shipperNumber:
          type: string
          description: This represents the shipper account number. Required when actionType is save.
          minLength: 6
          maxLength: 6
          example: X5R660
        actionType:
          type: string
          description: Specify the intent of the request. 'Save' will inherently perform validation.
          enum:
            - validate
            - save
        trackingNumber:
          type: string
          description: The lead 1Z number for the shipment. Required when actionType is save.
          minLength: 18
          maxLength: 18
          pattern: ^1Z[0-9A-Z]{16}$
          example: 1Z1234567891234560
        shipmentMetaData:
          $ref: '#/components/schemas/CustomDetailsRequestMetaDatav2'
        products:
          type: array
          description: Unbounded list of containers for products included on the shipment being updated
          minItems: 1
          items:
            type: object
            properties:
              productId:
                type: string
                description: An identifier for the product
                minLength: 1
                maxLength: 50
                example: PROD-001
              productDescription:
                type: string
                description: The description of the product
                minLength: 1
                maxLength: 105
                example: Sample pharma goods
              commodityCode:
                $ref: '#/components/schemas/CustomDetailsCommodityCodev2'
              productMetaData:
                $ref: '#/components/schemas/CustomDetailsRequestMetaDatav2'
            additionalProperties: false
            required:
              - productId
              - productDescription
              - productMetaData
      additionalProperties: false
      required:
        - actionType
    CustomDetailsGetFieldsSuccessResponsev2:
      type: object
      description: Contains commodity code groupings and the detailed field metadata required per country, process, and Regulation.
      properties:
        commodityCodes:
          type: array
          description: Unbounded list of commodity codes and their associated compliance Regulations.
          items:
            type: object
            properties:
              commodityCode:
                $ref: '#/components/schemas/CustomDetailsCommodityCodev2'
              regulations:
                type: array
                description: Regulations that require additional data for this commodity code.
                minItems: 1
                items:
                  type: object
                  properties:
                    regulation:
                      $ref: '#/components/schemas/CustomDetailsRegulationv2'
                    regulationSections:
                      $ref: '#/components/schemas/CustomDetailsRegulationSectionv2'
                  additionalProperties: false
                  required:
                    - regulation
            additionalProperties: false
            required:
              - commodityCode
              - regulations
        fieldGroups:
          type: array
          description: Unbounded list of field group definitions grouped by country, shipment type, and Regulation.
          minItems: 1
          items:
            type: object
            properties:
              countryCode:
                type: string
                description: The <a href="https://www.iso.org/iso-3166-country-codes.html" target="_blank">ISO 3166</a> country or territory code the fields pertain to.
                minLength: 2
                maxLength: 2
                pattern: ^[A-Z]{2}$
                example: US
              countryName:
                type: string
                description: Country name the fields apply to.
                example: UNITED STATES OF AMERICA
              shipmentType:
                type: string
                description: Indicates what direction of movement the fields pertain to.
                oneOf:
                  - title: Fields for import movment
                    const: Import
                  - title: Fields for export movement
                    const: Export
                  - title: Fields for both movements
                    const: Both
              groupKey:
                $ref: '#/components/schemas/CustomDetailsGroupKeyv2'
              details:
                type: string
                description: Provides details on why and when the information is needed.
                example: This is for US import FDA fields
              regulation:
                $ref: '#/components/schemas/CustomDetailsRegulationv2'
              regulationSections:
                $ref: '#/components/schemas/CustomDetailsRegulationSectionv2'
              fields:
                type: array
                description: Unbounded list of individual field definitions.
                minItems: 1
                items:
                  type: object
                  properties:
                    sectionKey:
                      $ref: '#/components/schemas/CustomDetailsSectionKeyv2'
                    label:
                      type: string
                      description: Human-readable name of the field.
                      example: Manufacturer Name
                    order:
                      type: string
                      description: Display order for the field.
                      minLength: 1
                      maxLength: 3
                      example: "1"
                    tooltip:
                      type:
                        - string
                        - "null"
                      description: Tooltip text explaining the field.
                      example: The name of the manufacturer for the product
                    isRequired:
                      type: string
                      description: Returns the conditionality of the field
                      oneOf:
                        - title: "Yes"
                          const: "Y"
                        - title: "No"
                          const: "N"
                        - title: "Conditional"
                          description: "If returned there will be at least one requirement condition"
                          const: "C"
                    requirementConditions:
                      type: 
                        - array
                        - "null"
                      description: Unbounded array of rules. Conditionally required when is 'isRequired' flag is set.
                      items:
                        type: object
                        description: |
                          An object containing the specifics of each rule. Order is to be applied
                          top-down (OR conditions align with the prior rule).
                        properties:
                          logicalOperator:
                            type: string
                            description: |
                              Determines how the rules are joined when evaluating the condition if there are multiple rules.
                              Required for all rules except the first.
                            enum:
                              - "AND"
                              - "OR"
                          fieldKey:
                            type:
                              - string
                              - "null"
                            description: The key for the field that this rule is evaluating
                            example: IN001
                          operator:
                            type:
                              - string
                              - "null"
                            description: The operator used when evaluating the rule
                            oneOf:
                              - title: Equals
                                const: "="
                              - title: Greater Than
                                const: ">"
                              - title: Less Than
                                const: "<"
                              - title: Not Equal To
                                const: "!="
                          value:
                            type:
                              - string
                              - "null"
                            description: The value used when evaluating the rule
                            example: CSB V
                        additionalProperties: false
                        required:
                          - fieldKey
                          - operator
                          - value                          
                    fieldType:
                      type: string
                      description: The type of the field, based on available html form inputs
                      enum:
                        - textbox
                        - list
                        - date
                        - radio
                        - checkbox
                        - textarea
                      example: textbox
                    allowedValueCount:
                      type: integer
                      description: Number of occurnces allowed for this field
                      minLength: 1
                      maxLength: 2
                      default: 1
                      example: 1
                    validation:
                      type: object
                      description: rule validation object
                      properties:
                        minLength:
                          type:
                            - integer
                            - "null"
                          description: The min length allowed for text fields
                          minLength: 1
                          maxLength: 2
                          minimum: 1
                          maximum: 99
                          example: 1
                        maxLength:
                          type:
                            - integer
                            - "null"
                          description: The max length allowed for text fields
                          minLength: 1
                          maxLength: 3
                          minimum: 1
                          maximum: 100
                          example: 10
                        errorMessage:
                          type:
                            - string
                            - "null"
                          description: Error Message
                          example: Enter a valid alpha numeric value.
                        dataType:
                          type: string
                          description: defines which type of values to look for
                          oneOf:
                            - title: Custom
                              description: user will be required to enter a custom regex pattern
                              const: Custom
                            - title: List
                              description: listValues will need to be populated with a list of possible values for the field
                              const: List
                            - title: Email
                              const: Email
                            - title: Text
                              const: Text
                            - title: Alphanumeric
                              const: Alphanumeric
                            - title: Number
                              const: Number
                            - title: Date
                              const: Date
                        regexPattern:
                          type:
                            - string
                            - "null"
                          description: |
                            A regex-based validation pattern for the field which should be applied when validating,
                            Required when the type is 'custom'.
                          example: ^[a-zA-Z0-9]+$
                        listValues:
                          type: array
                          description: Unbounded list of string values to validate against. Required for type 'List'
                          items:
                            type: object
                            description: value to validate against
                            properties:
                              displayText:
                                type: string
                                description: Value to display in the dropdown for consumers
                                examples:
                                  - GSTIN (Normal)
                                  - GSTIN (Govt Entities)
                                  - GSTIN (Diplomats)
                                  - PAN Number
                                  - TAN Number
                                  - Passport Number
                                  - Aadhaar Number
                                  - Voter Id
                              internalValue:
                                type: string
                                description: Internal value for each dropdown item that is hidden to consumers
                                examples:
                                  - GSTIN
                                  - GSTINGE
                                  - GSTIND
                                  - PANNO
                                  - TANNO
                                  - PASSNO
                                  - AADHAARNO
                                  - VID
                            additionalProperties: false
                            required:
                              - displayText
                              - internalValue
                      additionalProperties: false
                      required:
                        - minLength
                        - maxLength
                        - errorMessage
                        - dataType
                    regulationSections:
                      $ref: '#/components/schemas/CustomDetailsRegulationSectionv2'
                    keyAlias:
                      type:
                        - string
                        - "null"
                      description: Alias used to identify the field when mapping to downstream systems.
                      example: ManufacturerName
                    level:
                      type:
                        - string
                        - "null"
                      description: Indicates whether the field applies at the shipment or product level.
                      enum:
                        - Shipment
                        - Product
                      example: Product
                  additionalProperties: false
                  required:
                    - order
                    - sectionKey
                    - label
                    - tooltip
                    - isRequired
                    - fieldType
                    - allowedValueCount
                    - validation
              additionalProperties: false
            additionalProperties: false
            required:
              - countryCode
              - shipmentType
              - groupKey
              - details
              - fields
      additionalProperties: false
      required:
        - commodityCodes

    #COMMON
    CustomDetailsCommodityCodev2:
      type: string
      description: The tariff code for the product for the selected import country and process type
      minLength: 1
      maxLength: 15
      example: "300490"
    CustomDetailsGroupKeyv2:
      type: string
      description: Field group key returned by the GET endpoint used to scope the shipment metadata payload; value should match the selected `groupKey` from that response.
      minLength: 1
      maxLength: 50
      example: US-IMP-CDC
    CustomDetailsRequestMetaDatav2:
      type: array
      description: Unbounded list of containers for product metadata groups
      minItems: 1
      items:
        type: object
        properties:
          groupKey:
            $ref: '#/components/schemas/CustomDetailsGroupKeyv2'
          fields:
            type: array
            description: Unbounded list of key-value pairs describing product fields
            minItems: 1
            items:
              type: object
              properties:
                fieldKey:
                  type: string
                  description: Unique field identifier (1-50 chars) that must match a `fieldKey` returned by the GET response for the selected group (e.g., ImportLicenseNumber, CSBType, MnuNa). 
                  minLength: 1
                  maxLength: 50
                  examples:
                    - ImportLicenseNumber
                    - CSBType
                    - IECCode
                    - Amount
                    - CurrencyCode
                    - MnuNa
                    - MnuAdLn1Te
                    - MnuAdLn2Te
                    - MnuAdLn3Te
                    - MnuCtyNa
                    - MnuStPrvCd
                    - MnuCtyCd
                    - MnuPslCd
                regulationSections:
                  $ref: '#/components/schemas/CustomDetailsRegulationSectionv2'
                  description: Regulation sections for the field, copied from the GET response so the submission matches the returned metadata.
                fieldValue:
                  type: string
                  description: User-entered value for the matched `fieldKey` (up to 500 chars); populate with the value provided for the field returned by the GET endpoint.
                  minLength: 0
                  maxLength: 500
                  example: UPS Labs
              additionalProperties: false
              required:
                - fieldKey
                - fieldValue
        additionalProperties: false
        required:
          - fields
    CustomDetailsSectionKeyv2:
      type: string
      description: Identifier for the field.
      minLength: 1
      maxLength: 50
      examples:
        - Bio
        - CSB
        - Cos
        - Dev
        - Foo
    CustomDetailsRegulationv2:
      type: string
      description: Identifier for the compliance Regulation.
      minLength: 1
      maxLength: 50
      example: FDA
    CustomDetailsRegulationSectionv2:
      type: array
      description: Unbounded list of regulationSection definitions for this Regulation.
      minItems: 1
      items:
        type: object
        properties:
          sectionKey:
            description: Identifier for the field. Conditionaly required when sectionName is not present.
            $ref: '#/components/schemas/CustomDetailsSectionKeyv2'
          sectionName:
            type: string
            description: Human-readable regulationSection label. Conditionally required when sectionKey is not present.
            minLength: 1
            maxLength: 100
            example: Cosmetics
        additionalProperties: false
    CustomDetailsErrorResponsev2:
      type: object
      description: Response object for errors
      properties:
        response:
          description: Response container to store errors
          type: object
          properties: 
            errors:
              type: array
              description: Unbounded array containing one or more errors
              items: 
                type: object
                description: Error entity
                properties: 
                  code:
                    type: string
                    description: code for the given message
                    minLength: 1
                    example: "105.002"
                  message:
                    type: string
                    description: the warning or error message to be conveyed
                    minLength: 1
                    example: Supplied Key was not in the correct range.
                  description:
                    type: 
                      - string
                      - "null"
                    description: Internal description of the error
                    minLength: 1
                    example: INVALID_FIELD_KEY
                  field:
                    type:
                      - string
                      - "null"
                    description: The path to the field causing the error as returned from the backend services.
                    minLength: 1
                    example: shipperNumber
                  value:
                    type: 
                      - string
                      - "null"
                    description: The value that caused the error
                    minLength: 1
                    example: "789999"
                additionalProperties: false
                required: 
                  -  code
                  -  message
          required: 
            -  errors
          additionalProperties: false
      required: 
        - response
      additionalProperties: false