​

What is Metered Billing used for?

• Forwarding Hosting Costs: Sellers can be billed based on the hosting costs incurred, allowing developers to directly pass on the expenses associated with maintaining servers and infrastructure.

• Recouping Shipping Costs: For businesses selling physical products, they can be charged an additional fee to cover the costs associated with shipping.

• Charging by Usage: Sellers are billed based on their actual usage of the application or service, allowing for a more flexible and fair pricing model.

• GPT Token Usage: Sellers can be charged based on the amount of GPT tokens utilized, typically for accessing specific features or services within an application.

• Data Storage: Sellers can be billed based on the amount of data they store in an application, typically measured in gigabytes or terabytes.

— Anything else ✨

​

Getting started

In this example, we will be charging a Seller for videos uploaded. It is very expensive for us, so we want to charge the Seller for however much they upload.

We are going to charge them $10 per every 5GB uploaded.

​

1. Retrieve your product ID

Whop allows you to sell access to different pricing tiers. For example, you can charge a “Basic” and an “Enterprise” plan, which each different pricing structures.

The Basic product has no upfront cost (free to install) whereas the Enterprise product is $100 / month. The Enterprise product is built for power Sellers, as it gives them access to less expensive video costs.

We are going to use the List Products endpoint to find our product ID. I am going to use the SDK, like so:

const products = await WhopAPI.company().GET("/company/products", {});

Now that you have the list of products, choose which product you want to set your metered billing pricing for. We automatically make one product for you when you sign up.

Here’s how I set productId using the SDK:

if (products.isErr) {
  return <p>Could not fetch products</p>;
}

const productId = products.data.data[0].id;

​

2. Create your Billing items

There are two types of billing items.

​

Structured Billing items

When you know the exact cost per unit and want to display to the seller, you will create a structured billing item beforehand. In this model, you will specify the unit name, unit price, and how many units are included. For example, here is how we’d charge $10 for every 5 GB of videos uploaded:

{
  "name": "Video Usage",
  "product_id": "prod_xxxxxxxxxxxxx",
  "billing_type": "structured",
  "unit_name": "GBs",
  "unit_amount": 5,
  "unit_price": "10.00",
  "currency": "usd",
  "identifier": "video_usage"
}

Here is how to create it using the SDK

await WhopAPI.company().POST("/company/billing_items", {
  body: {
    name: "Video Usage",
    product_id: "prod_xxxxxxxxxxxxx",
    billing_type: "structured",
    unit_name: "GBs",
    unit_amount: 5,
    unit_price: "10,00",
    currency: "usd",
    identifier: "video_usage",
  },
});

​

Variable Billing items

If you do not know the price of your billing item (or costs) beforehand, such as when shipping a package, you will use variable billing items. These will allow you to charge different rates on demand.

Create a variable billing item using the Create a billing item endpoint..

Here is an example JSON body to pass up:

{
  "name": "Video Usage",
  "product_id": "prod_xxxxxxxxxxxxx",
  "billing_type": "variable",
  "currency": "usd",
  "identifier": "video_usage"
}

Here is how to create it using the SDK

await WhopAPI.company().POST("/company/billing_items", {
  body: {
    name: "Video Usage",
    product_id: "prod_xxxxxxxxxxxxx",
    billing_type: "variable",
    currency: "usd",
    identifier: "video_usage",
  },
});

​

3. Submit usage

Now you need to tell Whop how much the seller has used. To do this, we are going to use the Billing Usage API

​

Structured Billing Item

Let’s say the seller uploaded 69 GB of video today. You will create a billing usage object with the following JSON body:

{
  "company_id": "biz_xxxxxxxxxxxxxx",
  "billing_item_identifier": "video_usage",
  "quantity": 69
}

Here is how to create it using the SDK:

await WhopAPI.app().POST("/app/billing_usages", {
  body: {
    company_id: "biz_xxxxxxxxxxxxxx",
    billing_item_identifier: "video_usage",
    quantity: 69,
  },
});

​

Variable Billing Item

Here is an example of how to charge the user $127.41

{
  "company_id": "biz_xxxxxxxxxxxxxx",
  "billing_item_identifier": "video_usage",
  "amount": "127.41"
}

Here is how to create it using the SDK:

await WhopAPI.app().POST("/app/billing_usages", {
  body: {
    company_id: "biz_xxxxxxxxxxxxxx",
    billing_item_identifier: "video_usage",
    amount: 127.41,
  },
});

​

4. Get Paid

Daily, at 9am EST, Whop will aggregate all usage submitted in the prior 24 hours, and charge the seller for the total amount.

If a seller has pending usage charges from your app, but does not have a payment method on file, Whop will send them email reminders daily, prompting them to add one.

To know when the payment has been captured and succeeded, you can listen to the payment.succeeded webhook event. The receipt_id will also be shown in the Billing Usages response on the API, which you can then use to retrieve more information about the payment using the Retrieve a payment endpoint.

After your app’s usage is processed, it will be automatically added to your balance for withdrawal.