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.

Parameters

Request Path Parameters

- plan
- ID of the plan.

Request Header Parameters

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.
- nickname
- Brief description of the plan.
- metadata
- A JSON object defined by the client. See Metadata.

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.
- 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.
- 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.
- 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. 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

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

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
$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

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 -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'
-d '{
    "metadata": {
        "merchant_defined": "updated"
    },
    "nickname": "Basic parking"
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "f219f271-d957-4739-93a5-1d9385104c87"
    },
    "data": {
        "id": "plan_51788cf4ed1b672cb0a2a97773887f5b",
        "aggregate_usage": "sum",
        "amount": 0,
        "billing_scheme": "tiered",
        "created_at": 1592311574,
        "currency": "USD",
        "interval": "month",
        "interval_count": 1,
        "metadata": {
            "merchant_defined": true
        },
        "product": {
            "id": "product_ab9599d248f6d4d4311148aea68e20d0",
            "active": true,
            "attributes": [
                "location",
                "size"
            ],
            "created_at": 1592299027,
            "description": "Monthly parking - covered area, compact car",
            "images": [
                "64bit-encoded-image-1",
                "64bit-encoded-image-2"
            ],
            "metadata": {
                "merchant_defined": true
            },
            "name": "Monthly parking",
            "package_dimensions": {
                "height": 0,
                "length": 0,
                "weight": 0,
                "width": 0
            },
            "shippable": false,
            "skus": [],
            "statement_descriptor": "",
            "type": "services",
            "unit_label": "",
            "updated_at": 1592299027
        },
        "nickname": "Basic parking",
        "tiers": [
            {
                "amount": 15,
                "up_to": "inf",
                "flat_amount": 0
            }
        ],
        "tiers_mode": "volume",
        "transform_usage": {
            "divide_by": 0,
            "round": ""
        },
        "trial_period_days": 0,
        "usage_type": "licensed"
    }
}

Activate Plan

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'
-d '{
    "active": true
}
'

{
{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "47f18710-7bb3-4d3c-9910-c0950d20f1cf"
    },
    "data": {
        "id": "plan_889a7dc707b2ca13a815b008bec61a7d",
        "aggregate_usage": "sum",
        "amount": 5,
        "billing_scheme": "per_unit",
        "created_at": 1616315917,
        "currency": "USD",
        "interval": "day",
        "interval_count": 1,
        "metadata": {},
        "product": {
            "id": "product_903650fb06b7099413db8019c1646d4b",
            "active": true,
            "attributes": [],
            "created_at": 1616315223,
            "description": "",
            "images": [],
            "metadata": {},
            "name": "Acme music stream",
            "package_dimensions": {
                "height": 0,
                "length": 0,
                "weight": 0,
                "width": 0
            },
            "shippable": false,
            "skus": [],
            "statement_descriptor": "",
            "type": "services",
            "unit_label": "",
            "updated_at": 1616315223
        },
        "nickname": "Basic",
        "tiers": [],
        "tiers_mode": "",
        "transform_usage": {
            "divide_by": 1,
            "round": "up"
        },
        "trial_period_days": 0,
        "usage_type": "licensed",
        "active": true
    }
}

In this section:

Documentation