{
  "openapi": "3.0.1",
  "info": {
    "title": "Customs Product API",
    "description": "Customs Product APIs let you create and manage saved customs product records for international shipments. These records can be reused in shipment requests to prefill customs item details such as product description, origin country, HS tariff code, quantity, unit price, and product dimensions.\nUsing these APIs helps reduce repeated data entry and improves consistency when the same product details are used across multiple domestic/international shipments.\nSaved customs product identifiers can be passed in shipment/OMS workflows where customs item details are required.",
    "version": "1.0.0",
    "license": {
      "name": "PB Software License Agreement",
      "url": "https://www.pitneybowes.com/us/support/account/pitney-bowes-terms-and-conditions.html"
    }
  },
  "servers": [
    {
      "url": "https://api-sandbox.sendpro360.pitneybowes.com/shipping",
      "description": "Sandbox Server"
    },
    {
      "url": "https://api.sendpro360.pitneybowes.com/shipping",
      "description": "Production Server (uses live data)"
    },
    {
      "url": "https://api-ppd.shipping360.pitneybowes.com/ca/shipping",
      "description": "Sandbox Server for Canada"
    },
    {
      "url": "https://api.shipping360.pitneybowes.com/ca/shipping",
      "description": "Production Server for Canada"
    }
  ],
  "tags": [
    {
      "name": "Customs Product",
      "description": "APIs for managing saved customs product records used to prefill customs item details for domestic/international shipments."
    }
  ],
  "paths": {
    "/api/v1/customsproduct": {
      "post": {
        "tags": [
          "Customs Product"
        ],
        "summary": "Add Customs Product",
        "description": "This operation creates a customs product and returns its identifier. Use this identifier in shipment APIs to prefill customs item fields (HS tariff code, origin country, unit price, weight, quantity).\n> **Note**: Support for this capability in the Rate Shipment and Create Shipment APIs is under active development. It is targeted for upcoming release.\n",
        "operationId": "addCustomsProduct",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddCustomsProduct"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Customs Product identifier successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "customsProductId": {
                      "type": "string",
                      "description": "The generated customs product identifier that can be used as customs items for international shipments. The items/properties defined here can only be used in the [customsItems](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/createshipmentv2#shipment/createshipmentv2/t=request&path=&oneof=0/customs/customsitems) array.",
                      "example": "cp00000922010"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or Bad Request",
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "description": "Unauthorized Error",
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "500": {
            "description": "Internal Server Error",
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "get": {
        "tags": [
          "Customs Product"
        ],
        "summary": "Get all Customs Products",
        "description": "Returns a list of all Customs Products.\n",
        "operationId": "getCustomsProduct",
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "",
              "example": "productName,ASC",
              "default": null,
              "enum": [
                "productName,ASC"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "number",
              "description": "",
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "schema": {
              "type": "number",
              "description": "",
              "default": 1
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "A list of customs productss has beed retreived successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pageInfo": {
                      "type": "object",
                      "description": "Pagination details for the response.",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "Total number of records available.",
                          "example": 10
                        },
                        "pages": {
                          "type": "integer",
                          "description": "Total number of pages available.",
                          "example": 1
                        },
                        "page": {
                          "type": "integer",
                          "description": "",
                          "example": 1
                        },
                        "pageSize": {
                          "type": "integer",
                          "description": "",
                          "example": 20
                        }
                      }
                    },
                    "data": {
                      "type": "array",
                      "description": "List of customs products.",
                      "items": {
                        "$ref": "#/components/schemas/GetCustomsProductResponse"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or Bad Request",
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "description": "Unauthorized Error",
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "500": {
            "description": "Internal Server Error",
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/api/v1/customsproduct/{customsProductId}": {
      "get": {
        "tags": [
          "Customs Product"
        ],
        "summary": "Get Customs Product by Id",
        "description": "This operation retrieves the details of a specific Customs Product mapping by its unique `description`.  \nA customs product (description) represents a saved configuration of customs items defined for international shipment.\n",
        "operationId": "getCustomsProductbyId",
        "parameters": [
          {
            "in": "path",
            "name": "customsProductId",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Unique customs product identifier. This value is defined when the customs product is created and cannot be changed later."
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Specified customs product has beed retreived successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetCustomsProductResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or Bad Request",
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "description": "Unauthorized Error",
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "500": {
            "description": "Internal Server Error",
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "put": {
        "tags": [
          "Customs Product"
        ],
        "summary": "Update Customs Product",
        "description": "This operation Updates the details for the specified Customs Product.  \nThe customs product (description)  itself **cannot** be changed.\n",
        "operationId": "updateCustomsProduct",
        "parameters": [
          {
            "in": "path",
            "name": "customsProductId",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Unique customs product identifier. This value is defined when the customs product is created and cannot be changed."
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddCustomsProduct"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Customs Product description successfully updated."
          },
          "400": {
            "description": "Invalid or Bad Request",
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "description": "Unauthorized Error",
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "500": {
            "description": "Internal Server Error",
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Customs Product"
        ],
        "summary": "Delete Customs Product",
        "description": "This operation deletes the Customs Product by its unique `description`.",
        "operationId": "deleteCustomsProduct",
        "parameters": [
          {
            "in": "path",
            "name": "customsProductId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique customs product identifier. This value is defined when the customs product is created and cannot be changed."
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The specified customs product has been deleted successfully."
          },
          "400": {
            "description": "Invalid or Bad Request",
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "description": "Unauthorized Error",
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "500": {
            "description": "Internal Server Error",
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "responses": {
      "UnauthorizedError": {
        "description": "The request could not be authorized.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/error"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "The request could not be completed due to an internal error.",
        "content": {}
      },
      "BadRequestError": {
        "description": "Invalid request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Errors"
            }
          }
        }
      }
    },
    "schemas": {
      "error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "This is HTTP 401 Unauthorized response status code, that indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource."
          }
        },
        "required": [
          "message"
        ]
      },
      "Errors": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "List of errors.",
            "items": {
              "type": "object",
              "properties": {
                "errorCode": {
                  "type": "string",
                  "description": "This error can be validation_error or internal_error or not_found or already_exists",
                  "example": "validation_error"
                },
                "errorDescription": {
                  "type": "string",
                  "description": "The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).",
                  "example": "Customs Product not found"
                }
              }
            }
          }
        }
      },
      "AddCustomsProduct": {
        "type": "object",
        "required": [
          "description",
          "originCountryCode",
          "quantity",
          "unitPrice",
          "productDimensions"
        ],
        "properties": {
          "description": {
            "type": "string",
            "description": "Description of the product.",
            "example": "This is description of the product"
          },
          "originCountryCode": {
            "type": "string",
            "description": "ISO country code of the product origin.",
            "example": "US"
          },
          "hsTariffCode": {
            "type": "string",
            "description": "Harmonized System (HS) tariff code.",
            "example": "hsc01"
          },
          "quantity": {
            "type": "integer",
            "description": "Quantity of the product.",
            "example": 1
          },
          "unitPrice": {
            "type": "number",
            "format": "float",
            "description": "Unit price of this item.",
            "example": 10
          },
          "itemId": {
            "type": "string",
            "description": "Unique identifier for the commodity.",
            "example": "item1"
          },
          "url": {
            "type": "string",
            "description": "Product page URL for this item.",
            "example": "abc"
          },
          "productDimensions": {
            "type": "object",
            "description": "Physical details of the product (Item).",
            "required": [
              "weight",
              "weightUnit"
            ],
            "properties": {
              "length": {
                "type": "number",
                "format": "float",
                "description": "Length of the product.",
                "example": 10
              },
              "height": {
                "type": "number",
                "format": "float",
                "description": "Height of the product.",
                "example": 10
              },
              "width": {
                "type": "number",
                "format": "float",
                "description": "Width of the product.",
                "example": 10
              },
              "dimUnit": {
                "type": "string",
                "description": "Unit of measurement for dimensions.",
                "enum": [
                  "IN",
                  "CM"
                ],
                "example": "IN"
              }
            }
          },
          "weightUnit": {
            "type": "string",
            "description": "Unit of weight.",
            "enum": [
              "OZ",
              "GM"
            ],
            "example": "OZ"
          },
          "weight": {
            "type": "number",
            "format": "float",
            "description": "Weight of the product(Item).",
            "example": 10
          }
        }
      },
      "GetCustomsProductResponse": {
        "type": "object",
        "properties": {
          "customsProductId": {
            "type": "string",
            "description": "Customs product identifier.",
            "example": "MGW40jeQAZ3m"
          },
          "description": {
            "type": "string",
            "description": "Description of the product.",
            "example": "towel"
          },
          "originCountryCode": {
            "type": "string",
            "description": "ISO country code of the product origin.",
            "example": "US"
          },
          "hsTariffCode": {
            "type": "string",
            "description": "Harmonized System (HS) tariff code.",
            "example": "hsc01"
          },
          "quantity": {
            "type": "integer",
            "description": "Quantity of the product.",
            "example": 1
          },
          "unitPrice": {
            "type": "number",
            "format": "float",
            "description": "Unit price of the product.",
            "example": 10
          },
          "itemId": {
            "type": "string",
            "description": "Unique identifier for the commodity.",
            "example": "item1"
          },
          "url": {
            "type": "string",
            "description": "Product page URL.",
            "example": "abc"
          },
          "productDimensions": {
            "type": "object",
            "description": "Physical details of the product (Item).",
            "required": [
              "weight",
              "weightUnit"
            ],
            "properties": {
              "length": {
                "type": "number",
                "format": "float",
                "description": "Length of the product.",
                "example": 10
              },
              "height": {
                "type": "number",
                "format": "float",
                "description": "Height of the product.",
                "example": 10
              },
              "width": {
                "type": "number",
                "format": "float",
                "description": "Width of the product.",
                "example": 10
              },
              "dimUnit": {
                "type": "string",
                "description": "Unit of measurement for dimensions.",
                "enum": [
                  "IN",
                  "CM"
                ],
                "example": "IN"
              }
            }
          },
          "weightUnit": {
            "type": "string",
            "description": "Unit of weight.",
            "enum": [
              "OZ",
              "GM"
            ],
            "example": "OZ"
          },
          "weight": {
            "type": "number",
            "format": "float",
            "description": "Weight of the product(Item).",
            "example": 10
          }
        }
      },
      "UpdateCustomsProductRequest": {
        "type": "object",
        "required": [
          "weight",
          "weightUnit"
        ],
        "properties": {
          "description": {
            "type": "string",
            "description": "Description of the product/Item needs to be updated.",
            "example": "This is description of the product"
          },
          "originCountryCode": {
            "type": "string",
            "description": "ISO country code of the product origin.",
            "example": "US"
          },
          "hsTariffCode": {
            "type": "string",
            "description": "Harmonized System (HS) tariff code.",
            "example": "hsc01"
          },
          "quantity": {
            "type": "integer",
            "description": "Quantity of the product.",
            "example": 1
          },
          "unitPrice": {
            "type": "number",
            "format": "float",
            "description": "Unit price of this item.",
            "example": 10
          },
          "itemId": {
            "type": "string",
            "description": "Unique identifier for the commodity.",
            "example": "item1"
          },
          "url": {
            "type": "string",
            "description": "Product page URL for this item.",
            "example": "abc"
          },
          "productDimensions": {
            "type": "object",
            "description": "Physical details of the product (Item).",
            "required": [
              "weight",
              "weightUnit"
            ],
            "properties": {
              "length": {
                "type": "number",
                "format": "float",
                "description": "Length of the product.",
                "example": 10
              },
              "height": {
                "type": "number",
                "format": "float",
                "description": "Height of the product.",
                "example": 10
              },
              "width": {
                "type": "number",
                "format": "float",
                "description": "Width of the product.",
                "example": 10
              },
              "dimUnit": {
                "type": "string",
                "description": "Unit of measurement for dimensions.",
                "enum": [
                  "IN",
                  "CM"
                ],
                "example": "IN"
              }
            }
          },
          "weightUnit": {
            "type": "string",
            "description": "Unit of weight.",
            "enum": [
              "OZ",
              "GM"
            ],
            "example": "OZ"
          },
          "weight": {
            "type": "number",
            "format": "float",
            "description": "Weight of the product(Item).",
            "example": 10
          }
        }
      }
    }
  }
}