There is an issue with the spec I am not sure how to solve. The first simpler problem is that customs_item_id is marked as required and not-nullable, but it really should be nullable so it can be left out of the request. However the real issue is with the value property, as it's defined as:

value:
  allOf:
    - $ref: '#/components/schemas/monetary_value'
  description: The total value of the customs item

and a monetary value is expected to be a structure that contains the amount and currency type, so it's passed in the request like so:

Value = new MonetaryValue {
    Amount = 42.99,
    Currency = Currency.Usd,
},

but the problem is, in the response, it comes back as a single numeric value:

    "customs_items": [
      {
        "customs_item_id": "se-11825779",
        "description": "Product name",
        "quantity": 2,
        "value": 42.99,
        "harmonized_tariff_code": "",
        "country_of_origin": "US",
        "unit_of_measure": null
      }
    ],

So that is completely incorrect as far as the OpenAPI spec is concerned, but it's not clear to me how to fix it?

For now the service seems fine with just passing a raw number and it assumes it is in USD, so I am going with that for now.

Author: kendallb

openapi.yaml

@@ -7676,6 +7676,7 @@ components:
       properties:
         customs_item_id:
           readOnly: true
+          nullable: true
           allOf:
             - $ref: '#/components/schemas/se_id'
           description: A string that uniquely identifies the customs item
@@ -7692,9 +7693,9 @@ components:
           default: 0
           description: The quantity of this item in the shipment.
         value:
-          allOf:
-            - $ref: '#/components/schemas/monetary_value'
-          description: The declared customs value of each item
+          type: number
+          format: double
+          description: The declared customs value of each item in USD
         harmonized_tariff_code:
           type: string
           nullable: true