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:
Create a service product.
Create a tiered pricing plan.
Create a subscription.
Create a usage record.
1. Create a Service Product
Create a product of type service. See 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.
Plan With Tiered Graduated Pricing
Prerequisites
Product ID
This plan utilizes a tiered billing scheme with graduated pricing (see 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). 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 and 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.
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.
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. 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.
To simulate the end of a billing cycle in the sandbox, use Start a New Cycle.