# Calculate average balance

Calculates an average balance for an account.<br>
Using this endpoint, you can specify a datetime range and calculate the [average balance](https://www.investopedia.com/terms/a/average-balance.asp) of an account over that period. This involves multiplying the balance by the number of days it has remained unchanged, summing the results, and then dividing them by the total number of days in the specified period.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Banking - Interest-bearing accounts",
    "version": "1.0.0",
    "description": "API for interest-bearing account functionality",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/savings-products",
      "description": "Sandbox API server for testing"
    }
  ],
  "tags": [
    {
      "name": "Average balance",
      "description": "Endpoints that enable calculating average balances for an account"
    }
  ],
  "components": {
    "parameters": {
      "accountId": {
        "description": "Account ID",
        "in": "path",
        "name": "accountId",
        "required": true,
        "schema": {
          "type": "integer"
        },
        "example": 123456
      },
      "idempotencyHeader": {
        "name": "idempotency",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "required": true,
        "description": "A unique identifier for the request. If you need to retry a request, use the same idempotency key to avoid creating duplicate resources.\n",
        "example": "123e4567-e89b-12d3-a456-426614174000"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error type code",
            "example": "EIBACC0003"
          },
          "details": {
            "type": "string",
            "description": "Error details",
            "example": "error EIBACC0008: Validation error [(Field 'Order' is invalid)]"
          },
          "message": {
            "description": "Error message",
            "example": "Bad Request",
            "type": "string"
          }
        }
      },
      "CalculateAverageBalanceRequest": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "number",
            "description": "Account identifier.",
            "example": 123456
          },
          "begin_date_datetime": {
            "type": "string",
            "format": "date-time",
            "description": "The specified datetime when the average balance calculation begins. The datetime is displayed in the RFC 3339 format; for example: `2024-01-28T10:33:01Z`.\n",
            "example": "2024-01-28T10:33:01.000Z"
          },
          "end_date_datetime": {
            "type": "string",
            "format": "date-time",
            "description": "The specified datetime when the average balance calculation ends. The datetime is displayed in the RFC 3339 format; for example: `2024-01-29T10:33:01Z`.\n",
            "example": "2024-01-30T10:33:01.000Z"
          },
          "balance_types_to_calculate": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "available",
                "savings",
                "held_funds"
              ]
            },
            "description": "Choose a balance to calculate its average balance, you can select multiple balance types to calculate their average balances simultaneously. The balance types are:<br>\n* `available`\n* `savings`\n* `held_funds`\n",
            "example": [
              "available",
              "savings",
              "held_funds"
            ]
          }
        }
      },
      "CalculateAverageBalanceResponse": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "number",
            "description": "Account ID.",
            "example": 123456
          },
          "idempotency_key": {
            "type": "string",
            "description": "Idempotency key.",
            "example": "123e4567-e89b-12d3-a456-xyz"
          },
          "status": {
            "type": "string",
            "description": "Status of the average balance calculation request.",
            "enum": [
              "PROCESSING",
              "COMPLETE"
            ]
          },
          "message": {
            "type": "string",
            "description": "Message.",
            "example": "Request is under progress"
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "responses": {
      "400BadRequest": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              ]
            },
            "examples": {
              "invalidRequestBody": {
                "summary": "Bad Request",
                "value": {
                  "code": "EIBACC0008",
                  "message": "Bad Request",
                  "detail": "error EIBACC0008: Validation error [(Field 'Order' is invalid)]"
                }
              }
            }
          }
        }
      },
      "404NotFound": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              ]
            },
            "examples": {
              "invalidRequestBody": {
                "summary": "Bad Request",
                "value": {
                  "code": "EIBACC0064",
                  "message": "Product not found"
                }
              }
            }
          }
        }
      },
      "409Conflict": {
        "description": "Conflict",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              ]
            },
            "examples": {
              "conflict": {
                "summary": "Conflict",
                "value": {
                  "code": "EIBACC0114",
                  "message": "Product is already detached"
                }
              }
            }
          }
        }
      },
      "500InternalServer": {
        "description": "Internal error",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              ]
            },
            "examples": {
              "internalProcessingError": {
                "summary": "Internal processing error",
                "value": {
                  "code": "EIBACC0007",
                  "message": "Internal error",
                  "detail": "Internal error"
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/accounts/{accountId}/average-balance": {
      "post": {
        "tags": [
          "Average balance"
        ],
        "summary": "Calculate average balance",
        "description": "Calculates an average balance for an account.<br>\nUsing this endpoint, you can specify a datetime range and calculate the [average balance](https://www.investopedia.com/terms/a/average-balance.asp) of an account over that period. This involves multiplying the balance by the number of days it has remained unchanged, summing the results, and then dividing them by the total number of days in the specified period.\n",
        "operationId": "interest-bearing-calculate-average-balance",
        "parameters": [
          {
            "$ref": "#/components/parameters/idempotencyHeader"
          },
          {
            "$ref": "#/components/parameters/accountId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalculateAverageBalanceRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalculateAverageBalanceResponse"
                }
              }
            },
            "description": "Accepted"
          },
          "400": {
            "$ref": "#/components/responses/400BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/404NotFound"
          },
          "409": {
            "$ref": "#/components/responses/409Conflict"
          },
          "500": {
            "$ref": "#/components/responses/500InternalServer"
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}
```