{
"openapi": "3.0.1",
"info": {
"title": "Cost Account APIs",
"description": "These APIs provides Cost Account management operations like creating Cost account, modify, get and delete.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api-sandbox.sendpro360.pitneybowes.com/costaccountmgmt",
"description": "Sandbox Server"
},
{
"url": "https://api.sendpro360.pitneybowes.com/costaccountmgmt",
"description": "Production Server (uses live data)"
}
],
"tags": [
{
"name": "Cost Account Management",
"description": "APIs provide facility to create and manage cost accounts."
}
],
"paths": {
"/api/v1/costAccounts": {
"post": {
"tags": [
"Cost Account Management"
],
"summary": "Add Cost Account",
"description": "This operation creates cost account.
\n\n**Key Considerations:**\n\n - A cost account is an account used to maintain and segregate records for shipments, postage, and other operational data. There can be multiple Cost accounts, I.e; multiple Wallet - but one ledger. \n - Cost accounts allow to track which wallet was used for payment, maintain detailed payment history, and set budget notifications or thresholds.\n - Cost accounts are managed in a hierarchical structure: Enterprise > Division > Location.\n - Cost accounts can be assigned to a location, enabling client administrators to filter and analyze records based on the selected cost account.\n - A location can have one or more cost accounts assigned to it. This allows to filter shipments or postage records by selecting the cost account.\n - Cost accounts are assigned a status of either Active or Inactive.\n - Sub-Cost Accounts and Sub-Sub-Cost Accounts can also be created under the main cost account to further refine segregation.\n",
"operationId": "addCostAccount",
"parameters": [
{
"name": "X-PB-Developer-Partner-ID",
"in": "header",
"schema": {
"type": "string"
},
"description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.",
"required": false
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CostAccountRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Cost Account Added Successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CostAccountResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"tags": [
"Cost Account Management"
],
"summary": "Get Cost Accounts",
"description": "This operation gets cost account details",
"operationId": "getCostAccounts",
"parameters": [
{
"name": "X-PB-Developer-Partner-ID",
"in": "header",
"description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.",
"required": false,
"schema": {
"type": "string"
},
"example": ""
},
{
"name": "page",
"in": "query",
"description": "This indicates the page of the Cost account result list.",
"schema": {
"type": "string"
},
"example": "1"
},
{
"name": "size",
"in": "query",
"description": "This indicates the size/count of the searched result list.",
"schema": {
"type": "string"
},
"example": "10"
}
],
"responses": {
"200": {
"description": "Cost Accounts Fetched Successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetCostAccountsResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/costAccounts/{costaccountId}": {
"put": {
"tags": [
"Cost Account Management"
],
"summary": "Update Cost Account",
"description": "Update Cost Account",
"operationId": "updateCostAccount",
"parameters": [
{
"name": "costaccountId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-PB-Developer-Partner-ID",
"in": "header",
"description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateCostAccount"
}
}
}
},
"responses": {
"200": {
"description": "Specified cost account updated successfully."
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"tags": [
"Cost Account Management"
],
"summary": "Get Cost Account Details by Cost Account ID",
"description": "This operation gets the Cost account by cost account ID",
"operationId": "getCostAccount",
"parameters": [
{
"name": "costaccountId",
"in": "path",
"description": "Indicates costaccountId.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-PB-Developer-Partner-ID",
"in": "header",
"description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Cost Account get successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetCostAccountResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Cost Account Management"
],
"summary": "Delete Cost Account",
"description": "This operation archive the cost account",
"operationId": "deleteCostAccount",
"parameters": [
{
"name": "costaccountId",
"in": "path",
"description": "Indicates CostAccountID.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-PB-Developer-Partner-ID",
"in": "header",
"description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Cost Account Archived successful"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/costAccounts/importUrl": {
"post": {
"tags": [
"Cost Account Management"
],
"summary": "Create Cost Account Import Job",
"description": "This operation is used for creating a job for Cost Accounts Import. The payload for this endpoint is an empty JSON object {} because it does not require any additional data to be sent in the request body. jobID and url is returned in the response where user can upload csv file containing cost accounts. Download the sample-cost-accounts-import file.",
"operationId": "importCostAccount",
"parameters": [
{
"name": "X-PB-Developer-Partner-ID",
"in": "header",
"schema": {
"type": "string"
},
"description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.",
"required": false
}
],
"responses": {
"200": {
"description": "Cost Account Added Successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportCostAccountResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/costAccounts/batch/{jobID}/process": {
"post": {
"tags": [
"Cost Account Management"
],
"summary": "Process Import Cost Account Job",
"description": "This operation processes (executes) the existing Batch job. The `{jobID}` path parameter is required to identify which batch job to process. The payload for this endpoint is an empty JSON object {} because it does not require any additional data to be sent in the request body. Once the job is processed, system will read the uploaded csv file, validate the data and create cost accounts based on that. In case of any error in the file, cost account will not be created and error csv file will be generated for details of error.\nThe payload for this endpoint is an empty JSON object {} because it does not require any additional data to be sent in the request body. The `jobId` parameter in the endpoint URL specifies which batch of shipments to process.\n",
"operationId": "processImportCostAccount",
"parameters": [
{
"name": "X-PB-Developer-Partner-ID",
"in": "header",
"schema": {
"type": "string"
},
"description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.",
"required": false
},
{
"name": "jobID",
"description": "A unique identifier assigned to job which is automatically assigned by system while it is processed.",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Process Import cost Account",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessImportCostAccountResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/costAccounts/batch/{jobID}/status": {
"get": {
"tags": [
"Cost Account Management"
],
"summary": "Get Import Cost Account Job Status",
"description": "This operation retrieves the status of an existing Batch identified by `{jobID}`. The response will provide information about its current status and whether the job has been completed. In case of error, an error CSV file will be generated with details of the error.",
"operationId": "importCostAccountStatus",
"parameters": [
{
"name": "X-PB-Developer-Partner-ID",
"in": "header",
"schema": {
"type": "string"
},
"description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.",
"required": false
},
{
"name": "jobID",
"description": "This is the jobID which system generated in response of `Import Cost Account` API",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Cost Account Added Successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportCostAccountStatusResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
}
},
"components": {
"schemas": {
"CostAccountRequest": {
"type": "object",
"required": [
"name",
"code"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the cost account. When used in Shipment APIs, this field is referred to as `costAccountName`. ",
"example": "testname"
},
"code": {
"type": "string",
"description": "Code of the cost account. When used in Shipment APIs, this field is referred to as `costAccountCode`.",
"example": "test01"
},
"passwordEnabled": {
"type": "boolean",
"description": "Set to true when to enable password on cost account",
"example": true
},
"passwordCode": {
"type": "string",
"description": "Only required when passwordEnabled is true. this indicates the password you want to set. It should be alphanumeric and lenght of 4",
"example": "test"
},
"description": {
"type": "string",
"description": "this indicates the description you want to provide for cost account",
"example": "test cost account"
},
"status": {
"type": "boolean",
"description": "Setting true creates cost account as Active and setting false makes it inactive",
"example": true
},
"billable": {
"type": "boolean",
"description": "set to true in case want to make cost account billable",
"example": true
},
"parent": {
"type": "string",
"description": "this indicates cost account Id of parent account",
"example": ""
},
"advanceOption": {
"type": "object",
"description": "Additional configuration options for assigning the cost account to a specific hierarchy level (Enterprise, Division, or Location). If no permission is provided, the cost account is assigned to the Enterprise level by default.",
"properties": {
"permission": {
"type": "object",
"description": "Defines the hierarchy level and corresponding entity values where this cost account will be available.",
"properties": {
"permissionByEntity": {
"type": "string",
"description": "Indicates the hierarchy level at which the cost account is assigned.\nSupported values:\n",
"enum": [
"D",
"L",
"E"
]
},
"permissionByValue": {
"type": "array",
"description": "The list of identifiers corresponding to the selected hierarchy level.\nFor example:
\nDivision IDs if permissionByEntity = D
\nLocation IDs if permissionByEntity = L
\nEnterprise ID f permissionByEntity = E\n",
"items": {
"type": "string"
}
}
}
}
},
"example": {
"permission": {
"permissionByEntity": "D",
"permissionByValue": [
"div_auto_sac11be"
]
}
}
}
}
},
"GetCostAccountResponse": {
"type": "object",
"properties": {
"accountID": {
"type": "string",
"description": "it indicates unique cost account ID created by system",
"example": "absjf878"
},
"name": {
"type": "string",
"description": "this indicates the name of cost account",
"example": "name"
},
"code": {
"type": "string",
"description": "this indicates the code of cost account",
"example": "code"
},
"parent": {
"type": "string",
"description": "this indicates cost account Id of parent account",
"example": ""
},
"description": {
"type": "string",
"description": "this indicates the description you want to provide for cost account",
"example": "description"
},
"status": {
"type": "boolean",
"description": "It indicates if cost account is active or inactive"
},
"passwordEnabled": {
"type": "boolean",
"description": "It indicates if password is enabled on cost account"
},
"passwordCode": {
"type": "string",
"description": "It indicates password for the cost account",
"example": "test"
},
"billable": {
"type": "boolean",
"description": "It indicates if cost account is billable"
},
"advanceOption": {
"type": "object",
"description": "Additional configuration options for assigning the cost account to a specific hierarchy level (Enterprise, Division, or Location). If no permission is provided, the cost account is assigned to the Enterprise level by default.",
"properties": {
"permission": {
"type": "object",
"description": "Defines the hierarchy level and corresponding entity values where this cost account will be available.",
"properties": {
"permissionByEntity": {
"type": "string",
"description": "Indicates the hierarchy level at which the cost account is assigned.\nSupported values:\n",
"enum": [
"D",
"L",
"E"
]
},
"permissionByValue": {
"type": "array",
"description": "The list of identifiers corresponding to the selected hierarchy level.\nFor example:
\nDivision IDs if permissionByEntity = D
\nLocation IDs if permissionByEntity = L
\nEnterprise ID f permissionByEntity = E\n",
"items": {
"type": "string"
}
}
}
}
},
"example": {
"permission": {
"permissionByEntity": "D",
"permissionByValue": [
"div_auto_sac11be"
]
}
}
}
}
},
"GetCostAccountsResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "it displays all the cost accounts",
"items": {
"type": "object",
"properties": {
"accountID": {
"type": "string",
"description": "it indicates unique cost account ID created by system",
"example": "absh7830"
},
"name": {
"type": "string",
"description": "this indicates the name of cost account",
"example": "name"
},
"code": {
"type": "string",
"description": "this indicates the code of cost account",
"example": "code"
},
"parent": {
"type": "string",
"description": "this indicates cost account Id of parent account",
"example": ""
},
"description": {
"type": "string",
"description": "this indicates the description you want to provide for cost account",
"example": "description"
},
"status": {
"type": "boolean",
"description": "It indicates if cost account is active or inactive"
},
"passwordEnabled": {
"type": "boolean",
"description": "It indicates if password is enabled on cost account"
},
"passwordCode": {
"type": "string",
"description": "It indicates password for the cost account",
"example": "test"
},
"billable": {
"type": "boolean",
"description": "It indicates if cost account is billable"
},
"advanceOption": {
"type": "object",
"description": "Additional configuration options for assigning the cost account to a specific hierarchy level (Enterprise, Division, or Location). If no permission is provided, the cost account is assigned to the Enterprise level by default.",
"properties": {
"permission": {
"type": "object",
"description": "Defines the hierarchy level and corresponding entity values where this cost account will be available.",
"properties": {
"permissionByEntity": {
"type": "string",
"description": "Indicates the hierarchy level at which the cost account is assigned.\nSupported values:\n",
"enum": [
"D",
"L",
"E"
]
},
"permissionByValue": {
"type": "array",
"description": "The list of identifiers corresponding to the selected hierarchy level.\nFor example:
\nDivision IDs if permissionByEntity = D
\nLocation IDs if permissionByEntity = L
\nEnterprise ID f permissionByEntity = E\n",
"items": {
"type": "string"
}
}
}
}
},
"example": {
"permission": {
"permissionByEntity": "D",
"permissionByValue": [
"div_auto_sac11be"
]
}
}
}
}
}
}
}
},
"CostAccountResponse": {
"type": "object",
"properties": {
"accountID": {
"type": "string",
"description": "Unique cost account id generated by system. When used in Shipment APIs, this field is referred to as `costAccountId`."
}
}
},
"UpdateCostAccount": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "this indicates the description of cost account",
"example": "description"
},
"status": {
"type": "boolean",
"description": "this indicates if cost account is active"
},
"passwordEnabled": {
"type": "boolean",
"description": "this indicates if password is enabled"
},
"passwordCode": {
"type": "string",
"description": "this defines password set for the cost account",
"example": "test"
},
"billable": {
"type": "boolean",
"description": "this indicates if cost account is billable"
},
"advanceOption": {
"type": "object",
"description": "Additional configuration options for assigning the cost account to a specific hierarchy level (Enterprise, Division, or Location). If no permission is provided, the cost account is assigned to the Enterprise level by default.",
"properties": {
"permission": {
"type": "object",
"description": "Defines the hierarchy level and corresponding entity values where this cost account will be available.",
"properties": {
"permissionByEntity": {
"type": "string",
"description": "Indicates the hierarchy level at which the cost account is assigned.\nSupported values:\n",
"enum": [
"D",
"L",
"E"
]
},
"permissionByValue": {
"type": "array",
"description": "The list of identifiers corresponding to the selected hierarchy level.\nFor example:
\nDivision IDs if permissionByEntity = D
\nLocation IDs if permissionByEntity = L
\nEnterprise ID f permissionByEntity = E\n",
"items": {
"type": "string"
}
}
}
}
},
"example": {
"permission": {
"permissionByEntity": "D",
"permissionByValue": [
"div_auto_sac11be"
]
}
}
}
}
},
"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": "array",
"items": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "Error code(s) that appear due to HTTP 400- Invalid or Bad Request, e.g. validation-error.",
"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": "name - value missing."
},
"additionalInfo": {
"type": "string",
"description": "This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceid, or if the information is missing."
},
"additionalParameters": {
"type": "array",
"items": {
"type": "string",
"description": "The field(s) that might be incorrect in the request."
}
}
}
}
},
"NotFoundErrors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"example": "not_found",
"description": "Error code(s) that appear due HTTP 404 Page or File not found."
},
"errorDescription": {
"type": "string",
"example": "resource not found",
"description": "Document not found."
},
"additionalInfo": {
"type": "string",
"description": "Additional information about the error. This error 'Not Found' might appear due to `Cost Account Not Found`."
}
}
}
},
"ImportCostAccountResponse": {
"type": "object",
"properties": {
"jobID": {
"type": "string",
"description": "This is the system generated Job Id.",
"example": "L86wbedwBon"
},
"url": {
"type": "string",
"description": "This is url to which csv file would be uploaded for importing cost accounts",
"example": "https://225934331380-sp360-shared-services-iad-qa.s3.amazonaws.com/CostAccount/import/upload/sac9f07/L86wbedwBon/import-costaccount-5a907730-10a0-4e52-a193-d50a0c8a3d0c.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIATJGV4JX2F6MDPCWY%2F20230819%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230819T114328Z&X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEOz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIQDIoH3r4%2FoDb99MmVOIxECmLjIGc9lFQ8mIgp75wpd0TgIgGqrcq2A%2FJJDVvv3lQlDZo9Eodt7Cg8%2B9MnN3zyzu2p"
}
}
},
"ProcessImportCostAccountResponse": {
"type": "object",
"properties": {
"jobID": {
"type": "string",
"description": "It displays the jobID for which processing is requested",
"example": "L86wbedwBon"
},
"status": {
"type": "string",
"description": "It displays Job Status of submission, on successful submission it would show as Submitted",
"example": "SUBMITTED"
}
}
},
"ImportCostAccountStatusResponse": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "It shows the status of the Job- Completed or Failed",
"example": "Completed"
},
"jobID": {
"type": "string",
"description": "It shows the JobID of the import cost account",
"example": "L86wbedwBon"
},
"RecordCounts": {
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "this indicates the total number of records"
},
"success": {
"type": "number",
"description": "this indicates the number of success records"
},
"failed": {
"type": "number",
"description": "this indicates the number of failed records"
}
}
},
"errorFileURL": {
"type": "object",
"description": "It would only be visible when status is Failed",
"properties": {
"csv": {
"type": "string",
"description": "It shows the csv url which contains information about failed records",
"example": "https://225934331380-sp360-shared-services-iad-qa.s3.amazonaws.com/CostAccount/import/error/sac9f07/L86wbedwBon/Error-import-costaccount-5a907730-10a0-4e52-a193-d50a0c8a3d0c.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIATJGV4JX2K7OIRQGI%2F20230819%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230819T115234Z&X-Amz-Expires=900&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEOz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIEg6jXh8GVV82wgPUv9NINpspM42vrB2zVWsqr3%2BbmXlAiEAgBxvyeN7fJzMXF40NzFhzTnGur8mfcPkKpAO56kBIPAqxQUIpP%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARACGgwyMjU5MzQzMz"
}
}
}
}
}
},
"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"
}
}
}
},
"NotFoundError": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundErrors"
}
}
}
}
},
"securitySchemes": {
"basicAuth": {
"type": "http",
"scheme": "basic"
},
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}