How to implement volume-based subscription for webservice

[JasonSie1024]

Hi, I intend to implement a subscription billing model with PayPal Subscription API for a WebSocket as a service that I'm currently working on.

The plans will be a few tiers each with base price and extra fee for volumes exceeding the tier quota.

For example: a basic plan cost $10 with a quota for 5M messages and an extra fee of $1 per million messages. 

Kinda like the CloudFlare billing plan and they're also implement PayPal as their payment method, so I think this is possible.

But after I look through the PayPal subscription API, it seems like it's impossible to implement the extra fee part for exceeding volume used without user's approvement.

If there's anything I missed or misunderstood?

[MTS_Jennifer · Accepted solution]

Hi Jason,

Thank you for posting to the PayPal Community.

With Subscription API you can update a subscription's price via a Patch API call. You would need to write the script to check for the volume that the subscriber paid.

First run an api call to find out the current subscription details:

You need to confirm the sequence because you are going to be changing the pricing on the next payment.

https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_transactions

Request
GET https://api.sandbox.paypal.com/v1/billing/subscriptions/I-1Y39UM7WXXXX

Response
{
    "status": "ACTIVE",
    "status_update_time": "2023-03-28T11:38:27Z",
    "id": "I-1Y39UM7WXXXX",
    "plan_id": "XXXXXXX",
    "start_time": "2023-01-30T05:00:00Z",
    "quantity": "1",
    "shipping_amount": {
        "currency_code": "USD",
        "value": "0.0"
    },
    "subscriber": {
        "email_address": "xxxxxxx@xxxx",
        "payer_id": "XXXXXXX",
        "name": {
            "given_name": "Buyer",
            "surname": "BuyerTest"
        },
       
        },
        "cycle_executions": [
            {
                "tenure_type": "TRIAL",
                "sequence": 1,
                "cycles_completed": 1,
                "cycles_remaining": 0,
                "total_cycles": 1
            },
            {
                "tenure_type": "REGULAR",
                "sequence": 2,
                "cycles_completed": 2,
                "cycles_remaining": 10,
                "current_pricing_scheme_version": 1,
                "total_cycles": 12
            }
        ],
        "last_payment": {
            "amount": {
                "currency_code": "USD",
                "value": "16.5"
            },
            "time": "2023-03-28T11:38:26Z"
        },
        "next_billing_time": "2023-04-28T10:00:00Z",
        "final_payment_time": "2024-01-28T10:00:00Z",
        "failed_payments_count": 0
    },
    "create_time": "2023-01-29T15:38:05Z",
    "update_time": "2023-03-28T11:38:27Z",
    "plan_overridden": false,
    "links": [

After you know the sequence you can run a Patch Call on the next sequence. For the above example the next sequence would be 3, since two sequences have taken place. You can replace the price of the subscription with the new price starting at the next sequence.

Here is the example Patch API Call:

https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_patch

PATCH https://api.sandbox.paypal.com/v1/billing/subscriptions/I-1Y39UM7WXXXX
[
  {
    "op": "replace",
    "path": "/plan/billing_cycles/@sequence==3/pricing_scheme/fixed_price",
    "value": {
      "currency_code": "USD",
      "value": "10.00"
    }
  }
]

Thank you,

Jennifer

MTS

PayPal

[JasonSie1024]

Hi Jennifer,

Thank you for your fast reply!

It seems to be the answer I need, I will look into this more.

So the logic will become like: I need to constantly checking if a user has exceed their given quota for their plan, if so, then I calculate the fixed-price for next billing cycle and update it through the APIs you mentioned, right?

Thank you,

Jason

[MTS_Jennifer]

Hi @JasonSie1024,

You are correct that is the best option for updating your subscriptions.

Thank you,

Jennifer

MTS

PayPal