Create Plan

Create a pricing plan for services.

Relevant to a product that has type set to service.

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

Parameters

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.
  true
- aggregate_usage
- Determines which quantity is used to calculate the pricing. Required when usage_type is metered. Relevant when billing_scheme is set to per_unit. 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.
  sum
- amount
- The amount to charge, in units of the currency defined in currency. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal. For a free service, use 0.
  Relevant when billing_scheme is set to per_unit. When the billing_scheme is set to tiered, set the amount in the tiers array.
- billing_scheme
- Describes how to compute the price. One of the following:
  - per_unit - The amount specified in amount is charged for each unit. Also set these related fields: amount, transform_usage, usage_type, aggregate_usage.
  - tiered - The unit pricing is computed using a tiering strategy as defined with the tiers and tiers_mode fields.
  per_unit
- currency
- Three-letter ISO 4217 code for the currency used in fields that represent monetary amounts.
- id
- Unique ID for this plan. English alphanumeric characters with no special characters except underscore. If the client does not define an ID, Rapyd generates a string starting with plan_.
- interval
- Specifies the units used in defining the billing cycle. Maximum interval is 1 year. One of the following:
  - day
  - week
  - month
  - year
- interval_count
- Number of time intervals in the billing cycle. Integer. See interval.
  1
- metadata
- A JSON object defined by the client. See Metadata.
- nickname
- Brief description of the plan.
- product
- The ID of the product that this plan is for, or an object containing fields that describe the product in the plan.
- tiers
- Defines a tiered pricing structure. Array of objects. Each tier object represents a pricing tier. Relevant when billing_scheme is set to tiered. For more information, see Pricing Plans. 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. Relevant when billing_scheme is set to tiered. For more information, see Pricing Plans.
- 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.
  1
  round
  Indicates whether the reported number of units should be rounded up or down to the next whole quantity specified in divide_by.
  up
- 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. You must also set aggregate_usage.
  - licensed - The customer is billed even if the service is not used. For more information, see Transformation Pricing in Pricing Plans.
  licensed

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
            {
                var metadata = new
                {
                    merchant_defined = true
                };

               
                var requestObj = new
                {
                    amount = "9.99",
                    currency = "USD",
                    interval = "month",
                    product = "product_bae271e2e973594ed82b7d2b18a8b2ff",
                    aggregate_usage = "",
                    billing_scheme = "per_unit",
                    nickname = "sbp",
                    trial_period_days = "7",
                    usage_type = "licensed",
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/plans", 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 = {
      amount: '9.99',
      currency: 'USD',
      interval: 'month',
      product: 'product_4ba001c7655c4a0ee4f471dbaccaa305',
      aggregate_usage: '',
      billing_scheme: 'per_unit',
      nickname: 'sbp',
      metadata: {
        merchant_defined: true
      },
      trial_period_days: '7',
      usage_type: 'licensed'
    };
    const result = await makeRequest('POST', '/v1/plans', 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 = [
  "amount" =>  "9.99",
  "currency" =>  "USD",
        "interval" =>  "month",
        "product" =>  "product_bae271e2e973594ed82b7d2b18a8b2ff",
        "aggregate_usage" =>  "",
        "billing_scheme" =>  "per_unit",
        "nickname" =>  "sbp",
        "trial_period_days" =>  "7",
        "usage_type" =>  "licensed"
];

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

Python

from pprint import pprint

from utilities import make_request

plan = {
    "amount": "9.99",
    "currency": "USD",
    "interval": "month",
    "product": "product_bae271e2e973594ed82b7d2b18a8b2ff",
    "billing_scheme": "per_unit",
    "nickname": "sbp",
    "metadata": {
        "merchant_defined": True
    },
    "trial_period_days": "7",
    "usage_type": "licensed"
}
result = make_request(method='post', path='/v1/plans', body=plan)
pprint(result)

/v1/plans

Create Plan with Tiered Graduated Billing

curl -X post
https://sandboxapi.rapyd.net/v1/plans
-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 '{
    "currency": "USD",
    "product": "product_fa1b30b1caa6711910f60e758dbe70c6",
    "nickname": "Transit Use",
    "usage_type": "licensed",
    "trial_period_days": "0",
    "billing_scheme": "tiered",
    "tiers_mode": "graduated",
    "tiers": [
        {
            "amount": 4,
            "up_to": 5,
            "flat_amount": 1
        },
        {
            "amount": 3,
            "up_to": 10
        },
        {
            "amount": 2,
            "up_to": 20
        },
        {
            "amount": 1,
            "up_to": "inf"
        }
    ],
    "interval": "month",
    "interval_count": "1"
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "9a43aa30-f245-4256-8aaa-34b9ddb349a7"
    },
    "data": {
        "id": "plan_d2b079cfbe29fc802baf215aa64bb1fa",
        "aggregate_usage": "sum",
        "amount": 0,
        "billing_scheme": "tiered",
        "created_at": 1673499122,
        "currency": "USD",
        "interval": "month",
        "interval_count": 1,
        "metadata": {},
        "product": {
            "id": "product_fa1b30b1caa6711910f60e758dbe70c6",
            "active": true,
            "attributes": [
                "quantity"
            ],
            "created_at": 1673498178,
            "description": "Public Transportation Usage",
            "images": [
                "64bit-encoded-image-1"
            ],
            "metadata": {
                "merchant_defined": true
            },
            "name": "Transit Rides",
            "package_dimensions": {
                "height": 0,
                "length": 0,
                "weight": 0,
                "width": 0
            },
            "shippable": false,
            "skus": [],
            "statement_descriptor": "Transit Usage",
            "type": "services",
            "unit_label": "rides",
            "updated_at": 1673498178
        },
        "nickname": "Transit Use",
        "tiers": [
            {
                "amount": 4,
                "up_to": 5,
                "flat_amount": 1
            },
            {
                "amount": 3,
                "up_to": 10,
                "flat_amount": 0
            },
            {
                "amount": 2,
                "up_to": 20,
                "flat_amount": 0
            },
            {
                "amount": 1,
                "up_to": "inf",
                "flat_amount": 0
            }
        ],
        "tiers_mode": "graduated",
        "transform_usage": {
            "divide_by": 1,
            "round": "up"
        },
        "trial_period_days": 0,
        "usage_type": "licensed"
    }
}

Create Plan with Tiered Volume Billing

curl -X post
https://sandboxapi.rapyd.net/v1/plans
-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 '{
    "currency": "USD",
    "product": "product_88fde8f1365082b50e8f4b37127edd99",
    "nickname": "SaaS Users",
    "usage_type": "licensed",
    "trial_period_days": "0",
    "billing_scheme": "tiered",
    "tiers_mode": "volume",
    "tiers": [
        {
            "amount": 35,
            "up_to": 5,
            "flat_amount": 25
        },
        {
            "amount": 30,
            "up_to": 10
        },
        {
            "amount": 25,
            "up_to": 25
        },
        {
            "amount": 20,
            "up_to": 100
        },
        {
            "amount": 15,
            "up_to": 500
        },
        {
            "amount": 10,
            "up_to": "inf"
        }
    ],
    "interval": "month",
    "interval_count": "2"
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "5891b0f4-0953-4037-a89e-3c2a4a1dfc39"
    },
    "data": {
        "id": "plan_8b2e324c0d90c030acc9c40cff66e019",
        "aggregate_usage": "sum",
        "amount": 0,
        "billing_scheme": "tiered",
        "created_at": 1673509721,
        "currency": "USD",
        "interval": "month",
        "interval_count": 2,
        "metadata": {},
        "product": {
            "id": "product_88fde8f1365082b50e8f4b37127edd99",
            "active": true,
            "attributes": [
                "users"
            ],
            "created_at": 1673509005,
            "description": "SaaS Users",
            "images": [
                "64bit-encoded-image-1"
            ],
            "metadata": {
                "merchant_defined": true
            },
            "name": "SaaS Users",
            "package_dimensions": {
                "height": 0,
                "length": 0,
                "weight": 0,
                "width": 0
            },
            "shippable": false,
            "skus": [],
            "statement_descriptor": "Number of Users",
            "type": "services",
            "unit_label": "users",
            "updated_at": 1673509005
        },
        "nickname": "SaaS Users",
        "tiers": [
            {
                "amount": 35,
                "up_to": 5,
                "flat_amount": 25
            },
            {
                "amount": 30,
                "up_to": 10,
                "flat_amount": 0
            },
            {
                "amount": 25,
                "up_to": 25,
                "flat_amount": 0
            },
            {
                "amount": 20,
                "up_to": 100,
                "flat_amount": 0
            },
            {
                "amount": 15,
                "up_to": 500,
                "flat_amount": 0
            },
            {
                "amount": 10,
                "up_to": "inf",
                "flat_amount": 0
            }
        ],
        "tiers_mode": "volume",
        "transform_usage": {
            "divide_by": 1,
            "round": "up"
        },
        "trial_period_days": 0,
        "usage_type": "licensed"
    }
}

Create Plan with Transformation Pricing

curl -X post
https://sandboxapi.rapyd.net/v1/plans
-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 '{
    "amount": 1500,
    "currency": "USD",
    "product": "product_88fde8f1365082b50e8f4b37127edd99",
    "nickname": "Licenses",
    "usage_type": "licensed",
    "trial_period_days": "0",
    "billing_scheme": "per_unit",
    "transform_usage": {
        "divide_by": 5,
        "round": "up"
    },
    "interval": "month",
    "interval_count": "2"
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "137995a0-b968-4caa-b662-d40cfdda30aa"
    },
    "data": {
        "id": "plan_747e00631a2e8ef0322e5473ac1373dd",
        "aggregate_usage": "sum",
        "amount": 1500,
        "billing_scheme": "per_unit",
        "created_at": 1673873968,
        "currency": "USD",
        "interval": "month",
        "interval_count": 2,
        "metadata": {},
        "product": {
            "id": "product_88fde8f1365082b50e8f4b37127edd99",
            "active": true,
            "attributes": [
                "users"
            ],
            "created_at": 1673509005,
            "description": "SaaS Users",
            "images": [
                "64bit-encoded-image-1"
            ],
            "metadata": {
                "merchant_defined": true
            },
            "name": "SaaS Users",
            "package_dimensions": {
                "height": 0,
                "length": 0,
                "weight": 0,
                "width": 0
            },
            "shippable": false,
            "skus": [],
            "statement_descriptor": "Number of Users",
            "type": "services",
            "unit_label": "users",
            "updated_at": 1673509005
        },
        "nickname": "Licenses",
        "tiers": [],
        "tiers_mode": "",
        "transform_usage": {
            "divide_by": 5,
            "round": "up"
        },
        "trial_period_days": 0,
        "usage_type": "licensed"
    }
}

Create Plan with Metered Pricing

curl -X post
https://sandboxapi.rapyd.net/v1/plans
-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 '{
    "amount": 12.00,
    "currency": "USD",
    "product": "product_5a3e46804b01c4999cd061f032a02aea",
    "nickname": "Hourly Metered Parking",
    "trial_period_days": "0",
    "billing_scheme": "per_unit",
    "usage_type": "metered",
    "aggregate_usage": "sum",
    "transform_usage": {
        "divide_by": 60,
        "round": "up"
    },
    "interval": "day",
    "interval_count": "1"
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "16e0a30f-6f7b-4dcd-9137-7a80e83e04b7"
    },
    "data": {
        "id": "plan_ef238e1a7dea4b121c584dcbddb369ff",
        "aggregate_usage": "sum",
        "amount": 12,
        "billing_scheme": "per_unit",
        "created_at": 1673881640,
        "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": "Hourly Metered Parking",
        "tiers": [],
        "tiers_mode": "",
        "transform_usage": {
            "divide_by": 60,
            "round": "up"
        },
        "trial_period_days": 0,
        "usage_type": "metered"
    }
}

Create Plan with Trial Period

curl -X post
https://sandboxapi.rapyd.net/v1/plans
-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 '{
    "amount": 9.99,
    "currency": "USD",
    "interval": "month",
    "product": "product_4ba001c7655c4a0ee4f471dbaccaa305",
    "nickname": "Unlimited Plan",
    "usage_type": "licensed",
    "trial_period_days": "7"
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "a9073a41-aa8b-44ea-817f-66d0c25ae0f3"
    },
    "data": {
        "id": "plan_0c65651401695a12ccea5de0f38bf904",
        "aggregate_usage": "sum",
        "amount": 9.99,
        "billing_scheme": "per_unit",
        "created_at": 1673933015,
        "currency": "USD",
        "interval": "month",
        "interval_count": 1,
        "metadata": {},
        "product": {
            "id": "product_4ba001c7655c4a0ee4f471dbaccaa305",
            "active": true,
            "attributes": [
                "location",
                "size"
            ],
            "created_at": 1673932995,
            "description": "Unlimited music streaming",
            "images": [
                "64bit-encoded-image-1",
                "64bit-encoded-image-2"
            ],
            "metadata": {},
            "name": "Unlimited Music",
            "package_dimensions": {
                "height": 0,
                "length": 0,
                "weight": 0,
                "width": 0
            },
            "shippable": false,
            "skus": [],
            "statement_descriptor": "Music streaming",
            "type": "services",
            "unit_label": "month",
            "updated_at": 1673932995
        },
        "nickname": "Unlimited Plan",
        "tiers": [],
        "tiers_mode": "",
        "transform_usage": {
            "divide_by": 1,
            "round": "up"
        },
        "trial_period_days": 7,
        "usage_type": "licensed"
    }
}

Create Inactive Plan

curl -X post
https://sandboxapi.rapyd.net/v1/plans
-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 '{
    "amount": 9.99,
    "currency": "USD",
    "interval": "month",
    "product": "product_c4da1175a369d51273d1bfa1dcf90e1e",
    "nickname": "Unlimited Plan",
    "usage_type": "licensed",
    "trial_period_days": "7",
    "active": false
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "66bcc473-6868-4784-b955-6e2cb1fdf436"
    },
    "data": {
        "id": "plan_9e6cb6fb8a981bfea46c27271fb8eef9",
        "aggregate_usage": "sum",
        "amount": 9.99,
        "billing_scheme": "per_unit",
        "created_at": 1693830850,
        "currency": "USD",
        "interval": "month",
        "interval_count": 1,
        "metadata": {},
        "product": {
            "id": "product_c4da1175a369d51273d1bfa1dcf90e1e",
            "active": true,
            "attributes": [
                "location",
                "size"
            ],
            "created_at": 1693810492,
            "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": 1693810492
        },
        "nickname": "Unlimited Plan",
        "tiers": [],
        "tiers_mode": "",
        "transform_usage": {
            "divide_by": 1,
            "round": "up"
        },
        "trial_period_days": 7,
        "usage_type": "licensed",
        "active": false
    }
}

In this section:

Documentation