---
title: "Update Plan"
source_url: https://docs.rapyd.net/en/update-plan.html
lang: en
---

# Update Plan

Change or modify a pricing plan for services.

You can update a plan’s `nickname` or `metadata`.

This method triggers the **Plan Updated** webhook. This webhook contains the same information as the response.

> **Note:**
>
> - The code samples include successful requests (200) and bad requests (400).
>
>   - For error messages that appear due to bad requests (400), see:
>
>     - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors")
>     - [Plan Errors](https://docs.rapyd.net/en/plan-errors.md "Plan Errors")
>   - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors").

### Parameters

### Request Path Parameters

- - plan
  - ID of the plan.

### Request Header Parameters

- - access_key
  - Unique access key provided by Rapyd for each authorized user.

    See [Developers](https://docs.rapyd.net/en/developers.md "Developers").
- - Content-Type
  - Indicates that the data appears in JSON format. Set to **application/json**.
- - idempotency
  - A unique key that prevents the platform from creating the same object twice.

    See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency").
- - salt
  - Random string. Recommended length: 8-16 characters.
- - signature
  - Signature calculated for each request individually.

    See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures").
- - timestamp
  - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds).

### Request Body Parameters

- - active
  - Indicates whether the plan is available for a subscription. Can be **true** when the product associated with this plan is active.
- - metadata
  - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata").
- - nickname
  - Brief description of the plan.

### Response Parameters

- - active
  - Indicates whether the plan is available to be added to a subscription.
- - aggregate_usage
  - Determines which quantity is used to calculate the pricing. One of the following:

    - **max** - The maximum reported usage within the billing cycle.
    - **sum** - The sum of all usage during a billing cycle.
    - **last_during_period** - The last usage reported within the billing cycle.
    - **last_ever** - The last usage ever reported, if the latest billing cycles contain no usage at all.
- - amount
  - The amount to charge, in units of the currency defined in `currency`.

    Relevant when `billing_scheme` is set to **per_unit**.
- - billing_scheme
  - Describes how to compute the price. One of the following:

    - **per_unit** - The amount specified in `amount` is charged for each unit.
    - **tiered** - The unit pricing is computed using a tiering strategy as defined with the `tiers` and `tiers_mode` fields.
- - created_at
  - Time the `plan` object was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time").
- - currency
  - Three-letter ISO 4217 code for the currency used in fields that represent monetary amounts.
- - id
  - Unique ID for this plan.
- - interval
  - Specifies the units used in defining the billing cycle. One of the following:

    - **day**
    - **week**
    - **month**
    - **year**
- - interval_count
  - Number of time intervals in the billing cycle. Integer. See `interval`.
- - metadata
  - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata").
- - nickname
  - Brief description of the plan.
- - product
  - Describes this product in the plan. For details of the fields in the 'product' object, see [Create Product](https://docs.rapyd.net/en/create-product.md "Create Product").
- - tiers
  - Defines a tiered pricing structure. Each tier object represents a pricing tier. Relevant when `billing_scheme` is set to **tiered**. Contains the following fields:

    - `amount` - The price for each item in this tier. Decimal number.
    - `up_to` - The upper volume limit for this tier. Valid values: **inf** (infinite) or an integer.
    - `flat_amount` - Extra amount added to the entire tier. Default is 0.
- - tiers_mode
  - Determines the mode for calculating the total tiered charge. One of the following values:

    - **graduated** - The total cost at each price tier is calculated separately, then all tier charges are added together.
    - **volume** - The total cost is calculated as the number of service units multiplied by the applicable tier price.
- - transform_usage
  - Defines the transformation that is applied to the reported usage before the billed price is computed. The transformation divides the quantity by the divisor specified in `divide_by`, then rounds up or down according to the setting in `round`. Relevant when `billing_scheme` is set to **per_unit**. Relevant when `billing_scheme` is set to **per_unit**. For more information, see **Transformation Pricing** in [Pricing Plans](https://docs.rapyd.net/en/plan-542850.md#UUID-1bf47980-9184-1c69-7a42-11128cd18cf6_UUID-7a4550ef-636e-1f11-6a3e-0c123f5455eb "Pricing Plans"). Contains the following fields:

    - - divide_by
      - Indicates the divisor in the transformation calculation. Integer.
    - - round
      - Indicates whether the reported number of units should be rounded **up** or **down** to the next whole quantity specified in `divide_by`.
- - trial_period_days
  - The number of days in the customer's free trial period. Integer. Range: 0-730.
- - usage_type
  - Determines whether the customer is billed when the service is not actually used. Relevant when `billing_scheme` is set to **per_unit**. One of the following:

    - **metered** - The customer is billed only for actual usage.
    - **licensed** - The customer is billed even if the service is not used.

### Code Samples

- - .NET

    - ```csharp
      using System;
      using System.Text.Json;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      string plan = "plan_51788cf4ed1b672cb0a2a97773887f5b";

                      var metadata = new
                      {
                          merchant_defined = "updated"
                      };

                      var requestObj = new
                      {
                          metadata,
                          nickname = "Basic parking"
                      };

                      string request = JsonSerializer.Serialize(requestObj);

                      string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/plans/{plan}", request);

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```javascript
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const body = {
            nickname: 'main plan'
          };
          const result = await makeRequest(
            'POST',
            '/v1/plans/plan_51788cf4ed1b672cb0a2a97773887f5b',
            body
          );

          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - PHP

    - ```php
      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      $body = [
          "nickname" => "Basic parking"
      ];

      try {
          $object = make_request('post', '/v1/plans/plan_51788cf4ed1b672cb0a2a97773887f5b', $body);
          var_dump($object);
      } catch(Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```python
      from pprint import pprint

      from utilities import make_request

      plan_data = {
          "metadata": {
              "merchant_defined": "updated"
          },
          "nickname": "Basic parking"
      }
      result = make_request(method='post', path='/v1/plans/plan_51788cf4ed1b672cb0a2a97773887f5b', body=plan_data)
      pprint(result)
      ```

- /v1/plans/:plan

- Update Plan
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/plans/plan_51788cf4ed1b672cb0a2a97773887f5b' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "nickname": "Basic parking"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "2ff82671-6a3c-46c5-b6d2-67dd03fb4b23"
      },
      "data": {
          "id": "plan_19d3a529a2ffcd6ea077cd3ddd58356b",
          "aggregate_usage": "sum",
          "amount": 12,
          "billing_scheme": "per_unit",
          "created_at": 1761210476,
          "currency": "USD",
          "interval": "day",
          "interval_count": 1,
          "metadata": {},
          "product": {
              "id": "product_5a3e46804b01c4999cd061f032a02aea",
              "active": true,
              "attributes": [
                  "location",
                  "size"
              ],
              "created_at": 1673881298,
              "description": "Covered parking - compact car",
              "images": [
                  "64bit-encoded-image-1"
              ],
              "metadata": {},
              "name": "Hourly parking",
              "package_dimensions": {
                  "height": 0,
                  "length": 0,
                  "weight": 0,
                  "width": 0
              },
              "shippable": false,
              "skus": [],
              "statement_descriptor": "Hourly parking",
              "type": "services",
              "unit_label": "day",
              "updated_at": 1673881298
          },
          "nickname": "Basic parking",
          "tiers": [],
          "tiers_mode": "",
          "transform_usage": {
              "divide_by": 60,
              "round": "up"
          },
          "trial_period_days": 0,
          "usage_type": "metered",
          "active": true
      }
  }
  ```

- Activate Plan
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/plans/plan_889a7dc707b2ca13a815b008bec61a7d' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "active": true
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "ab1b2d51-ad16-44cf-88db-edc7d75bc926"
      },
      "data": {
          "id": "plan_19d3a529a2ffcd6ea077cd3ddd58356b",
          "aggregate_usage": "sum",
          "amount": 12,
          "billing_scheme": "per_unit",
          "created_at": 1761210476,
          "currency": "USD",
          "interval": "day",
          "interval_count": 1,
          "metadata": {},
          "product": {
              "id": "product_5a3e46804b01c4999cd061f032a02aea",
              "active": true,
              "attributes": [
                  "location",
                  "size"
              ],
              "created_at": 1673881298,
              "description": "Covered parking - compact car",
              "images": [
                  "64bit-encoded-image-1"
              ],
              "metadata": {},
              "name": "Hourly parking",
              "package_dimensions": {
                  "height": 0,
                  "length": 0,
                  "weight": 0,
                  "width": 0
              },
              "shippable": false,
              "skus": [],
              "statement_descriptor": "Hourly parking",
              "type": "services",
              "unit_label": "day",
              "updated_at": 1673881298
          },
          "nickname": "Basic parking",
          "tiers": [],
          "tiers_mode": "",
          "transform_usage": {
              "divide_by": 60,
              "round": "up"
          },
          "trial_period_days": 0,
          "usage_type": "metered",
          "active": true
      }
  }
  ```

- Bad Request - Plan Not Found
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/plans/plan_fa293db8739fb7085869ac7ccbcdca6' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "active": true
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "ERROR_GET_PLAN",
          "status": "ERROR",
          "message": "The request tried to retrieve a plan, but the plan was not found. The request was rejected. Corrective action: Use a valid plan ID.",
          "response_code": "ERROR_GET_PLAN",
          "operation_id": "bdc3b836-266f-4eae-9b5f-06278fe92a7c"
      }
  }
  ```