---
title: "Creating a Subscription With Tiered Pricing"
source_url: https://docs.rapyd.net/en/creating-a-subscription-with-tiered-pricing.html
lang: en
---

# Creating a Subscription With Tiered Pricing

How to create a subscription with a tiered pricing plan.

This procedure describes how to create a subscription that has a tiered pricing plan. The procedure is made up of the following steps:

1. Create a service product.
2. Create a tiered pricing plan.
3. Create a subscription.
4. Create a usage record.

### 1. Create a Service Product

Create a product of type **service**. See [Create Product](https://docs.rapyd.net/en/create-product.md "Create Product").

In this example, the service is transit rides on public transportation.

- - Create Product - Request

    - ```
      // Request URL: get https://sandboxapi.rapyd.net/v1/products

      // Message body:

      {
        "id": "",
        "name": "Transit Rides",
        "type": "services",
        "active":  true,
        "attributes": [
          "quantity"
         ],
        "description": "Public Transportation Usage",
        "images": [
          "64bit-encoded-image-1"
        ],
        "metadata": {
            "merchant_defined": true
        },
        "shippable": false,
        "statement_descriptor": "Transit Usage",
        "unit_label": "rides"
      }
      ```
- - Create Product - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "9f337790-4199-4ecd-9500-6936490a0d02"
          },
          "data": {
              "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
          }
      }
      ```

The response contains the **product ID** that is needed to create a plan.

### 2. Create a Tiered Pricing Plan

The Plan defines the pricing structure for a single product of type **service**. See [Create Plan](https://docs.rapyd.net/en/create-plan.md "Create Plan").

### Plan With Tiered Graduated Pricing

**Prerequisites**

- Product ID

This plan utilizes a **tiered** billing scheme with **graduated** pricing (see [Pricing Plans](https://docs.rapyd.net/en/plan-542850.md#UUID-1bf47980-9184-1c69-7a42-11128cd18cf6_UUID-7a4550ef-636e-1f11-6a3e-0c123f5455eb "Pricing Plans")). Each tier defines a price per unit in the `amount` field and the range that price applies to in the `up_to` field. A flat fee per billing cycle can be defined in the `flat_amount` field of the first tier. It appears as a separate line item in invoices.

In this example, the billing includes a $1 per month flat fee plus usage fees based on the following table.

| Number of Rides | Price per Ride |
| --- | --- |
| 1 to 5 | $4 |
| 6 to 10 | $3 |
| 11 to 20 | $2 |
| 21 or more | $1 |

In this scenario, a customer using public transportation 25 times during a monthly billing cycle will be charged $61:

- 5 rides at $4: $20
- 5 rides at $3: $15
- 10 rides at $2: $20
- 5 rides at $1: $5
- Flat amount: $1

This sample code creates a plan for the public transportation scenario described above.

- - Create Plan With Tiered Graduated Pricing - Request

    - ```
      // Request URL: post https://sandboxapi.rapyd.net/v1/plans

      // Message body:
      {
          "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"
      }
      ```
- - Create Plan With Tiered Graduated Pricing - Response

    - ```
      {
          "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"
          }
      }
      ```

The response contains the **plan ID** that is needed to create a subscription.

### Plan With Tiered Volume Pricing

**Prerequisites**

- Product ID

This plan utilizes a **tiered** billing scheme with **volume** pricing (see [Pricing Plans](https://docs.rapyd.net/en/plan-542850.md#UUID-1bf47980-9184-1c69-7a42-11128cd18cf6_UUID-7a4550ef-636e-1f11-6a3e-0c123f5455eb "Pricing Plans")). Each tier defines a price per unit in the `amount` field and the range that price applies to in the `up_to` field. A flat fee per billing cycle can be defined in the `flat_amount` field of each tier. Each flat fee appears as a separate line item in invoices.

A tiered volume plan can be used to offer discounted volume pricing based on the tier level the customer achieves during the billing cycle. This example illustrates license fees for SaaS software, based on the number of users. The customer is billed a $25 per month flat fee if they have 1 to 10 users. However, there is no flat amount for 11 or more users. The amounts charged are calculated according to the definition of the highest tier achieved during the billing cycle.

| Number of Users | Price per User | Flat Amount |
| --- | --- | --- |
| 1 to 5 | $35 | $25 |
| 6 to 10 | $30 | $25 |
| 11 to 25 | $25 | $0 |
| 26 to 100 | $20 | $0 |
| 101 to 500 | $15 | $0 |
| 501 to infinity | $10 | $0 |

In this scenario:

- The charge for 5 users is $200: $25 flat amount + (5 x $35)
- The charge for 10 users is $325: $25 flat amount + (10 x $30)
- The charge for 150 users is $2250: $0 flat amount + (150 x $15)

This sample code creates a plan for the software user scenario described above.

- - Create Plan With Tiered Volume Pricing - Request

    - ```
      // Request URL: post https://sandboxapi.rapyd.net/v1/plans

      // Message body:

      {
          "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,
                  "flat_amount": 25
              }, 
              {
                  "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"
      }
      ```
- - Create Plan With Tiered Volume Pricing - Response

    - ```
      {
          "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": 25
                  },
                  {
                      "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"
          }
      }
      ```

The response contains the **plan ID** that is required for creating a subscription.

### 3. Create a Subscription

**Prerequisites**

- Plan ID
- ID of a customer that has a default payment method. See [Create Customer](https://docs.rapyd.net/en/create-customer.md "Create Customer") and [Add Payment Method to Customer](https://docs.rapyd.net/en/add-payment-method-to-customer.md "Add Payment Method to Customer").

Create a subscription using a tiered billing scheme for recurring payments.

> **Note:**
>
> The `trial_period_days` and `simultaneous_invoice` plan and subscription settings determine when Rapyd collects the first payment. See [Create Subscription](https://docs.rapyd.net/en/create-subscription.md "Create Subscription").

This example uses the plan created above for a tiered billing scheme with graduated pricing. The steps are the same for the volume pricing plan. See [Create Subscription](https://docs.rapyd.net/en/create-subscription.md "Create Subscription").

- - **Create a Subscription - Request**

    - ```
      // Request URL: POST https://sandboxapi.rapyd.net/v1/payments/subscriptions

      // Message body:
      {
          "customer": "cus_5bee14584a78638ba717e746be62ee01",
          "billing": "pay_automatically",
          "cancel_at_period_end": false,
          "payment_method": "card_794ddbfd19fcc548c8399ca957f11a24",
          "subscription_items": [
          {
                  "plan": "plan_d2b079cfbe29fc802baf215aa64bb1fa",
                  "quantity": 1
              }
          ]
      }
      ```
- - **Create a Subscription - Response**

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "60a7e98c-17d3-40aa-a4a1-8e99a8738ebd"
          },
          "data": {
              "id": "sub_17b55f5ccfe97f80fe73a7acc0545386",
              "billing": "pay_automatically",
              "billing_cycle_anchor": 1673499338,
              "created_at": 1673499338,
              "customer_token": "cus_5bee14584a78638ba717e746be62ee01",
              "days_until_due": 30,
              "metadata": {},
              "tax_percent": 0,
              "cancel_at_period_end": false,
              "canceled_at": null,
              "current_period_end": 1674104138,
              "current_period_start": 1673499338,
              "discount": null,
              "ended_at": null,
              "subscription_items": {
                  "data": [
                      {
                          "id": "subi_a6f17fb61f9cad3c86327dd71dfaeb0c",
                          "created": 1673499338,
                          "metadata": null,
                          "quantity": 1,
                          "plan": {
                              "id": "plan_d2b079cfbe29fc802baf215aa64bb1fa",
                              "aggregate_usage": "sum",
                              "amount": 0,
                              "billing_scheme": "tiered",
                              "created_at": 1673499122,
                              "currency": "USD",
                              "interval": "week",
                              "interval_count": 1,
                              "metadata": {},
                              "product": "product_fa1b30b1caa6711910f60e758dbe70c6",
                              "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"
                          }
                      }
                  ],
                  "has_more": false,
                  "total_count": 0,
                  "url": "/v1/subscription_items?subscription=sub_17b55f5ccfe97f80fe73a7acc0545386"
              },
              "status": "active",
              "trial_end": null,
              "trial_start": null,
              "payment_method": "card_794ddbfd19fcc548c8399ca957f11a24",
              "payment_fields": null,
              "payout_fields": null,
              "type": "payment",
              "simultaneous_invoice": false
          }
      }
      ```

The response includes the **subscription ID** and the **subscription item ID** that are needed for creating usage records and updating subscriptions.

### 4. Create Usage Record

If the usage quantity differs from the quantity entered when the subscription was created, then you must change the **subscription_item** quantity. See [Create Usage Record](https://docs.rapyd.net/en/create-usage-record.md "Create Usage Record"). If no change is needed, then skip this step.

In this example, 25 transit rides are added to the previous total by setting `action` to **increment**.

- - Create Usage Record - Request

    - ```
      // Request URL: post https://sandboxapi.rapyd.net/v1/subscription_items/subi_a6f17fb61f9cad3c86327dd71dfaeb0c/usage_records

      // Message body:

      {
         "quantity": "25",
         "timestamp": "1673499783",
         "action" : "increment"
      }
      ```
- - Create Usage Record - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "e9f57f1d-ead5-45e1-9610-08af0fb12bf6"
          },
          "data": {
              "id": "subiur_ea14be559624d4e3043fce830868ec2a",
              "quantity": 25,
              "timestamp": "1674048649",
              "subscription_item": "subi_a6f17fb61f9cad3c86327dd71dfaeb0c"
          }
      }
      ```

You can change the quantity multiple times during a billing cycle.

For the setting of `action`,

- Use **increment** to increase the quantity. This number is added to the previous total usage.
- Use **set** change the quantity to the new value you set.

> **Note:**
>
> If weekly usage records are created during a billing cycle with quantities of 10, 8, 12, with the last entry being 10, using the `action`:
>
> - **increment** each time will result in a total of 40 units at the end of the billing cycle.
> - **set** each time (or just the last entry) will result in a total of 10 at the end of the billing cycle because that was the last number entered and **set** overwrites the previous entries.