{
  "openapi": "3.0.1",
  "info": {
    "title": "Ship via Code APIs",
    "description": "Ship Via Code APIs provide capabilities to create and manage reusable shipping configurations that combine carrier, carrier account, parcel type, service, and special services into a single identifier. <br/>These APIs help simplify shipment creation by allowing you to reference a predefined ship via code instead of repeatedly providing the same carrier configuration details in each request. <br/>The APIs support the following services:\n- Create a ship via code with predefined carrier configuration\n- Retrieve all ship via codes or a specific code by identifier\n- Update an existing ship via code configuration\n- Delete a ship via code\n<br/>Use these APIs to standardize shipping configurations, reduce repetitive input, and streamline shipment workflows when using the Create Shipment API.\n",
    "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": "Ship Via Code",
      "description": "APIs Provide services to manage reusable ship via codes that simplify shipment creation by encapsulating carrier, service, and parcel configuration."
    }
  ],
  "paths": {
    "/api/v1/shipviacode": {
      "post": {
        "tags": [
          "Ship Via Code"
        ],
        "summary": "Create Ship Via Code",
        "description": "Create a ship via code that represents a specific combination of carrier, carrier account, \nparcel type, service, and special services.  \nThis ship via code can then be used in the **Create Shipment API**, so users don't need to manually \nre-enter these parameters each time.  \nOnce generated, the code can be reused across multiple shipments to reduce effort in shipping requests.\n",
        "operationId": "createShipViaCode",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCarrierCustomCodeRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Ship Via Code successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "The generated ship via code that can be reused in Create Shipment API.",
                      "example": "FEDEX-custom-code1"
                    }
                  }
                }
              }
            }
          },
          "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": [
          "Ship Via Code"
        ],
        "summary": "Get all Ship Via Codes",
        "description": "Returns a list of ship via codes.\n",
        "operationId": "getShipViaCodes",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "A list of ship via codes has beed retreived successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/GetCustomCarrierCodeResponse"
                  }
                }
              }
            }
          },
          "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/shipviacode/{code}": {
      "get": {
        "tags": [
          "Ship Via Code"
        ],
        "summary": "Get Ship via Code by Code",
        "description": "This operation retrieves the details of a specific ship via code mapping by its unique `code`.  \nA ship via code represents a saved configuration of carrier, carrier account, parcel, service, and special services.\n",
        "operationId": "getShipViaCodeByCode",
        "parameters": [
          {
            "in": "path",
            "name": "code",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique ship via code identifier. This value is defined when the ship via code is created and cannot be changed."
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Specified ship via codes has beed retreived successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetCustomCarrierCodeResponse"
                }
              }
            }
          },
          "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": [
          "Ship Via Code"
        ],
        "summary": "Update Ship Via Code",
        "description": "This operation Updates the configuration for the specified ship via code.  \nThe ship via code  itself **cannot** be changed. If provided in the body, it will be ignored.\n",
        "operationId": "updateShipViaCode",
        "parameters": [
          {
            "in": "path",
            "name": "code",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique ship via code identifier. This value is defined when the ship via code is created and cannot be changed."
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCarrierCustomCodeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ship via code successfully updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "The updated ship via code that can be used in Create Shipment API.",
                      "example": "myups-test2"
                    }
                  }
                }
              }
            }
          },
          "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": [
          "Ship Via Code"
        ],
        "summary": "Delete Ship Via Code",
        "description": "This operation deletes the ship via code mapping by its unique `code`.",
        "operationId": "deleteShipViaCode",
        "parameters": [
          {
            "in": "path",
            "name": "code",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique ship via code identifier. This value is defined when the ship via code is created and cannot be changed."
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The specified ship via code 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": "Custom Fields not found"
                }
              }
            }
          }
        }
      },
      "CreateCarrierCustomCodeRequest": {
        "type": "object",
        "required": [
          "code",
          "carrier",
          "carrierAccountId"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Unique ship via code value defined by the client.",
            "example": "FEDEX-custom-code1"
          },
          "carrier": {
            "type": "string",
            "description": "Carrier name associated with the custom configuration.",
            "example": "FEDEX"
          },
          "carrierAccountId": {
            "type": "string",
            "description": "Unique identifier of the carrier account under which shipments will be processed.",
            "example": "xxxxxxxxxxx"
          },
          "parcelType": {
            "type": "string",
            "description": "Parcel type (e.g., PKG for package, LTR for letter).",
            "example": "PKG"
          },
          "parcelName": {
            "type": "string",
            "description": "Human-readable name for the parcel type (optional).",
            "example": "Package"
          },
          "serviceId": {
            "type": "string",
            "description": "Identifier of the shipping service to be used.",
            "example": "GRD"
          },
          "serviceName": {
            "type": "string",
            "description": "Human-readable name of the shipping service (optional).",
            "example": "Ground"
          },
          "specialServices": {
            "type": "array",
            "description": "List of special services applied to the ship via code.",
            "items": {
              "type": "object",
              "properties": {
                "specialServiceId": {
                  "type": "string",
                  "description": "Identifier of the special service.",
                  "example": "INS"
                },
                "inputParameters": {
                  "type": "array",
                  "description": "Input parameters for the special service.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Parameter name.",
                        "example": "INPUT_VALUE"
                      },
                      "value": {
                        "type": "string",
                        "description": "Parameter value.",
                        "example": "101"
                      }
                    }
                  }
                },
                "fee": {
                  "type": "number",
                  "description": "Monetary fee associated with the service (if any).",
                  "example": 0
                }
              }
            }
          }
        }
      },
      "customCarrierCodesResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Unique identifier to represent the custom carrier configuration. This code will be used later in Create Shipment API.\n- Allowed: letters, digits, dot, underscore, hyphen (need to confirm with team)\n",
            "example": "FEDEX-custom-code1"
          }
        }
      },
      "GetCustomCarrierCodeResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier generated by the system for the ship via code.",
            "example": "68b6bf44e10c804a9c1441df"
          },
          "code": {
            "type": "string",
            "description": "Ship via code value.",
            "example": "FEDEX-custom-code"
          },
          "subID": {
            "type": "string",
            "description": "Subscription ID associated with this ship via code.",
            "example": "sac4c3a"
          },
          "carrier": {
            "type": "string",
            "description": "Carrier name.",
            "example": "FEDEX"
          },
          "carrierAccountId": {
            "type": "string",
            "description": "Unique identifier of the carrier account.",
            "example": "B9PZAR2QZzn01Xo"
          },
          "parcelType": {
            "type": "string",
            "description": "Parcel type (e.g., PKG, LTR).",
            "example": "PKG"
          },
          "serviceId": {
            "type": "string",
            "description": "Identifier of the service selected for the shipment.",
            "example": "NDA"
          },
          "specialServices": {
            "type": "array",
            "description": "List of special services applied to the ship via code.",
            "items": {
              "type": "object",
              "properties": {
                "specialServiceId": {
                  "type": "string",
                  "description": "Identifier of the special service.",
                  "example": "INS"
                },
                "inputParameters": {
                  "type": "array",
                  "description": "Input parameters for the special service.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Parameter name.",
                        "example": "INPUT_VALUE"
                      },
                      "value": {
                        "type": "string",
                        "description": "Parameter value.",
                        "example": "101"
                      }
                    }
                  }
                },
                "fee": {
                  "type": "number",
                  "description": "Monetary fee associated with the service (if any).",
                  "example": 0
                }
              }
            }
          },
          "residential": {
            "type": "boolean",
            "example": false
          },
          "insertTimestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the entry was created.",
            "example": "2025-09-02T09:56:20.851Z"
          },
          "updateTimestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the entry was last updated.",
            "example": "0001-01-01T00:00:00Z"
          },
          "createdBy": {
            "type": "string",
            "description": "User ID of the creator.",
            "example": "0oa2fok3669kX7can0h8"
          },
          "archived": {
            "type": "boolean",
            "description": "Indicates whether the record is archived.",
            "example": false
          }
        }
      },
      "UpdateCarrierCustomCodeRequest": {
        "type": "object",
        "required": [
          "carrier",
          "carrierAccountId"
        ],
        "properties": {
          "carrier": {
            "type": "string",
            "description": "Carrier name associated with the custom configuration.",
            "example": "FEDEX"
          },
          "carrierAccountId": {
            "type": "string",
            "description": "Unique identifier of the carrier account under which shipments will be processed.",
            "example": "xxxxxxxxxxx"
          },
          "parcelType": {
            "type": "string",
            "description": "Parcel type (e.g., PKG for package, LTR for letter).",
            "example": "PKG"
          },
          "parcelName": {
            "type": "string",
            "description": "Human-readable name for the parcel type (optional).",
            "example": "Package"
          },
          "serviceId": {
            "type": "string",
            "description": "Identifier of the shipping service to be used.",
            "example": "GRD"
          },
          "serviceName": {
            "type": "string",
            "description": "Human-readable name of the shipping service (optional).",
            "example": "Ground"
          },
          "specialServices": {
            "type": "array",
            "description": "List of special services applied to the ship via code.",
            "items": {
              "type": "object",
              "properties": {
                "specialServiceId": {
                  "type": "string",
                  "description": "Identifier of the special service.",
                  "example": "INS"
                },
                "inputParameters": {
                  "type": "array",
                  "description": "Input parameters for the special service.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Parameter name.",
                        "example": "INPUT_VALUE"
                      },
                      "value": {
                        "type": "string",
                        "description": "Parameter value.",
                        "example": "101"
                      }
                    }
                  }
                },
                "fee": {
                  "type": "number",
                  "description": "Monetary fee associated with the service (if any).",
                  "example": 0
                }
              }
            }
          }
        }
      }
    }
  }
}