# Interest Rate Plans
> Interest Rate Plans are used to calculate the interest rate for accounts.

[Events](https://increase.com/documentation/webhooks.md) will be generated for this resource. The possible event categories are: `interest_rate_plan.created` and `interest_rate_plan.updated`.

## The Interest Rate Plan object
### Example
```json
{
  "created_at": "2020-01-31T23:59:59Z",
  "id": "interest_rate_plan_tgj91bw7fhrhlw23hpo8",
  "idempotency_key": null,
  "interest_rate": "0.055",
  "interest_rate_calculation": {
    "base_plus_offset": null,
    "calculation_method": "fixed_rate",
    "fixed_rate": {
      "value": "0.055"
    },
    "percentage_of_base": null
  },
  "name": "Interest Rate Plan 1",
  "path": "/interest_rate_plans/interest_rate_plan_tgj91bw7fhrhlw23hpo8",
  "program_id": "program_i2v2os4mwza1oetokh9i",
  "status": "active",
  "type": "interest_rate_plan"
}
```
### Attributes
- `created_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) time at which the Interest Rate Plan was created.

- `id` (string)
  The Interest Rate Plan identifier.

- `idempotency_key` (string, nullable)
  The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `interest_rate` (string)
  The interest rate currently being earned according to the Interest Rate Plan, as a string containing a decimal number. For example, a 1% interest rate would be represented as "0.01".

- `interest_rate_calculation` (dictionary)
  How the interest rate is calculated for this Interest Rate Plan.

  - `interest_rate_calculation.base_plus_offset` (dictionary, nullable)
    The base rate and offset used to calculate the interest rate for this Interest Rate Plan. Will be present if and only if the `calculation_method` is equal to `base_plus_offset`.

      - `interest_rate_calculation.base_plus_offset.base_rate` (enum)
        Which base rate is used to calculate the interest rate.
        Cases:
        * `top_of_federal_funds_target_range` (The top of the Federal Funds target range.)
        * `prior_month_federal_funds_effective_rate` (The prior month's Federal Funds effective rate.)
        * `prior_business_day_effective_federal_funds_rate` (The prior business day's Effective Federal Funds Rate.)
        * `last_business_day_of_prior_month_effective_federal_funds_rate` (The Effective Federal Funds Rate from the last business day of the prior month.)
        * `bank_prime_loan_rate` (The Bank Prime Loan Rate.)

      - `interest_rate_calculation.base_plus_offset.offset` (string)
        The offset from the base rate as a string containing a decimal number. For example, 1% would be represented as "0.01".

  - `interest_rate_calculation.calculation_method` (enum)
    The method used to calculate the interest rate.
    Cases:
    * `fixed_rate` (The rate is a fixed value.)
    * `base_plus_offset` (The rate is calculated as a fixed offset from a base rate.)
    * `percentage_of_base` (The rate is calculated as a fixed percentage of a base rate.)

  - `interest_rate_calculation.fixed_rate` (dictionary, nullable)
    The fixed interest rate for this Interest Rate Plan. Will be present if and only if the `calculation_method` is equal to `fixed_rate`.

      - `interest_rate_calculation.fixed_rate.value` (string)
        The fixed interest rate as a string containing a decimal number. For example, 1% would be represented as "0.01".

  - `interest_rate_calculation.percentage_of_base` (dictionary, nullable)
    The base rate and percentage used to calculate the interest rate for this Interest Rate Plan. Will be present if and only if the `calculation_method` is equal to `percentage_of_base`.

      - `interest_rate_calculation.percentage_of_base.base_rate` (enum)
        Which base rate is used to calculate the interest rate.
        Cases:
        * `top_of_federal_funds_target_range` (The top of the Federal Funds target range.)
        * `prior_month_federal_funds_effective_rate` (The prior month's Federal Funds effective rate.)
        * `prior_business_day_effective_federal_funds_rate` (The prior business day's Effective Federal Funds Rate.)
        * `last_business_day_of_prior_month_effective_federal_funds_rate` (The Effective Federal Funds Rate from the last business day of the prior month.)
        * `bank_prime_loan_rate` (The Bank Prime Loan Rate.)

      - `interest_rate_calculation.percentage_of_base.percentage` (string)
        The percentage of the base rate as a string containing a decimal number. For example, 50% would be represented as "0.50".

- `name` (string)
  The name you choose for the Interest Rate Plan.

- `program_id` (string)
  The identifier of the Program determining the compliance and commercial terms of this Interest Rate Plan.

- `status` (enum)
  The status of the Interest Rate Plan.
  Cases:
  * `active` (The Interest Rate Plan can be assigned to Accounts.)
  * `archived` (The Interest Rate Plan can no longer be assigned to Accounts. Accounts already using it are unaffected.)

- `type` (string)
  A constant representing the object's type. For this resource it will always be `interest_rate_plan`.

## List Interest Rate Plans
GET /interest_rate_plans

### Example
```curl
curl \
  --url "${INCREASE_URL}/interest_rate_plans" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

### Query Parameters
- `cursor` (string, optional)
  Return the page of entries after this one.

- `limit` (integer, optional)
  Limit the size of the list that is returned. The default (and maximum) is 100 objects.
  Default: `100`

- `program_id` (string, optional)
  Filter Interest Rate Plans to those belonging to the specified Program.

- `status.in` (array of enums, optional)
  Return results whose value is in the provided list. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.

  Cases:
  * `active` (The Interest Rate Plan can be assigned to Accounts.)
  * `archived` (The Interest Rate Plan can no longer be assigned to Accounts. Accounts already using it are unaffected.)

- `idempotency_key` (string, optional)
  Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

### Returns a Interest Rate Plan List object:
```json
{
  "data": [
    {
      "created_at": "2020-01-31T23:59:59Z",
      "id": "interest_rate_plan_tgj91bw7fhrhlw23hpo8",
      "idempotency_key": null,
      "interest_rate": "0.055",
      "interest_rate_calculation": {
        "base_plus_offset": null,
        "calculation_method": "fixed_rate",
        "fixed_rate": {
          "value": "0.055"
        },
        "percentage_of_base": null
      },
      "name": "Interest Rate Plan 1",
      "path": "/interest_rate_plans/interest_rate_plan_tgj91bw7fhrhlw23hpo8",
      "program_id": "program_i2v2os4mwza1oetokh9i",
      "status": "active",
      "type": "interest_rate_plan"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create an Interest Rate Plan
POST /interest_rate_plans

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/interest_rate_plans" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "interest_rate_calculation": {
      "calculation_method": "fixed_rate",
      "fixed_rate": {
        "value": "0.01"
      }
    },
    "name": "Tier 1",
    "program_id": "program_i2v2os4mwza1oetokh9i"
  }'
```

### Body Parameters
- `interest_rate_calculation` (dictionary, required)
  How the interest rate is calculated for this Interest Rate Plan.

  - `interest_rate_calculation.base_plus_offset` (dictionary, optional)
    The base rate and offset used to calculate the interest rate. Required if `calculation_method` is equal to `base_plus_offset`.

      - `interest_rate_calculation.base_plus_offset.base_rate` (enum, required)
        Which base rate is used to calculate the interest rate.

        Cases:
        * `top_of_federal_funds_target_range` (The top of the Federal Funds target range.)
        * `prior_month_federal_funds_effective_rate` (The prior month's Federal Funds effective rate.)
        * `prior_business_day_effective_federal_funds_rate` (The prior business day's Effective Federal Funds Rate.)
        * `last_business_day_of_prior_month_effective_federal_funds_rate` (The Effective Federal Funds Rate from the last business day of the prior month.)
        * `bank_prime_loan_rate` (The Bank Prime Loan Rate.)

      - `interest_rate_calculation.base_plus_offset.offset` (string, required)
        The offset from the base rate as a string containing a decimal number. For example, 1% would be represented as "0.01".

  - `interest_rate_calculation.calculation_method` (enum, required)
    The method used to calculate the interest rate.

    Cases:
    * `fixed_rate` (The rate is a fixed value.)
    * `base_plus_offset` (The rate is calculated as a fixed offset from a base rate.)
    * `percentage_of_base` (The rate is calculated as a fixed percentage of a base rate.)

  - `interest_rate_calculation.fixed_rate` (dictionary, optional)
    The fixed interest rate. Required if `calculation_method` is equal to `fixed_rate`.

      - `interest_rate_calculation.fixed_rate.value` (string, required)
        The fixed interest rate as a string containing a decimal number. For example, 1% would be represented as "0.01".

  - `interest_rate_calculation.percentage_of_base` (dictionary, optional)
    The base rate and percentage used to calculate the interest rate. Required if `calculation_method` is equal to `percentage_of_base`.

      - `interest_rate_calculation.percentage_of_base.base_rate` (enum, required)
        Which base rate is used to calculate the interest rate.

        Cases:
        * `top_of_federal_funds_target_range` (The top of the Federal Funds target range.)
        * `prior_month_federal_funds_effective_rate` (The prior month's Federal Funds effective rate.)
        * `prior_business_day_effective_federal_funds_rate` (The prior business day's Effective Federal Funds Rate.)
        * `last_business_day_of_prior_month_effective_federal_funds_rate` (The Effective Federal Funds Rate from the last business day of the prior month.)
        * `bank_prime_loan_rate` (The Bank Prime Loan Rate.)

      - `interest_rate_calculation.percentage_of_base.percentage` (string, required)
        The percentage of the base rate as a string containing a decimal number. For example, 50% would be represented as "0.50".

- `name` (string, required)
  The name you choose for the Interest Rate Plan.

- `program_id` (string, required)
  The identifier of the Program the Interest Rate Plan falls under.

## Retrieve an Interest Rate Plan
GET /interest_rate_plans/{interest_rate_plan_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/interest_rate_plans/interest_rate_plan_tgj91bw7fhrhlw23hpo8" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `interest_rate_plan_id` (string, required)
  The identifier of the Interest Rate Plan.

## Update an Interest Rate Plan
PATCH /interest_rate_plans/{interest_rate_plan_id}

### Example
```curl
curl -X "PATCH" \
  --url "${INCREASE_URL}/interest_rate_plans/interest_rate_plan_tgj91bw7fhrhlw23hpo8" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "name": "Tier 1"
  }'
```
### Path Parameters
- `interest_rate_plan_id` (string, required)
  The identifier of the Interest Rate Plan to update.

### Body Parameters
- `interest_rate_calculation` (dictionary, optional)
  How the interest rate is calculated for this Interest Rate Plan.

  - `interest_rate_calculation.base_plus_offset` (dictionary, optional)
    The base rate and offset used to calculate the interest rate. Required if `calculation_method` is equal to `base_plus_offset`.

      - `interest_rate_calculation.base_plus_offset.base_rate` (enum, required)
        Which base rate is used to calculate the interest rate.

        Cases:
        * `top_of_federal_funds_target_range` (The top of the Federal Funds target range.)
        * `prior_month_federal_funds_effective_rate` (The prior month's Federal Funds effective rate.)
        * `prior_business_day_effective_federal_funds_rate` (The prior business day's Effective Federal Funds Rate.)
        * `last_business_day_of_prior_month_effective_federal_funds_rate` (The Effective Federal Funds Rate from the last business day of the prior month.)
        * `bank_prime_loan_rate` (The Bank Prime Loan Rate.)

      - `interest_rate_calculation.base_plus_offset.offset` (string, required)
        The offset from the base rate as a string containing a decimal number. For example, 1% would be represented as "0.01".

  - `interest_rate_calculation.calculation_method` (enum, required)
    The method used to calculate the interest rate.

    Cases:
    * `fixed_rate` (The rate is a fixed value.)
    * `base_plus_offset` (The rate is calculated as a fixed offset from a base rate.)
    * `percentage_of_base` (The rate is calculated as a fixed percentage of a base rate.)

  - `interest_rate_calculation.fixed_rate` (dictionary, optional)
    The fixed interest rate. Required if `calculation_method` is equal to `fixed_rate`.

      - `interest_rate_calculation.fixed_rate.value` (string, required)
        The fixed interest rate as a string containing a decimal number. For example, 1% would be represented as "0.01".

  - `interest_rate_calculation.percentage_of_base` (dictionary, optional)
    The base rate and percentage used to calculate the interest rate. Required if `calculation_method` is equal to `percentage_of_base`.

      - `interest_rate_calculation.percentage_of_base.base_rate` (enum, required)
        Which base rate is used to calculate the interest rate.

        Cases:
        * `top_of_federal_funds_target_range` (The top of the Federal Funds target range.)
        * `prior_month_federal_funds_effective_rate` (The prior month's Federal Funds effective rate.)
        * `prior_business_day_effective_federal_funds_rate` (The prior business day's Effective Federal Funds Rate.)
        * `last_business_day_of_prior_month_effective_federal_funds_rate` (The Effective Federal Funds Rate from the last business day of the prior month.)
        * `bank_prime_loan_rate` (The Bank Prime Loan Rate.)

      - `interest_rate_calculation.percentage_of_base.percentage` (string, required)
        The percentage of the base rate as a string containing a decimal number. For example, 50% would be represented as "0.50".

- `name` (string, optional)
  The name you choose for the Interest Rate Plan.

- `status` (enum, optional)
  The status of the Interest Rate Plan.

  Cases:
  * `active` (The Interest Rate Plan can be assigned to Accounts.)
  * `archived` (The Interest Rate Plan can no longer be assigned to Accounts. Accounts already using it are unaffected.)