Metered Billing

Metered billing allows you to bill customers for charges incurred during a billing cycle. These charges could be from usage, one-off purchases, prorations, or some other amount not accounted for by the customer's subscription.

Introduction

Conceptually metered billing on Invoiced is simple. It's just line items! Metered billing should feel natural if you are already familiar with our invoicing API.

Pending Line Items

Whenever a customer incurs a charge with your business that you want to bill for later then you create a pending line item. A pending line item behaves just like invoice line items, with the distinction that it has not been billed yet. The line item is attached to a customer but not an invoice.

Invoicing pending line items

Pending line items get billed to the customer by issuing an invoice. When a pending line item is billed then it will be moved from the customer's account to an invoice. There are two ways that pending line items can be invoiced:

  1. Automatically at the end of a customer's billing period. Any pending line items will be swept up into the next subscription invoice.

  2. Manually triggering an invoice from pending line items. Use this method if you do not want to wait for the end of the billing cycle or your customer does not have a subscription.

Implementing metered billing

We are going to walk you through a basic metered billing workflow using the Invoiced API.

Choose your language

Create a customer

In order to bill our customer, we must first create an account for them on Invoiced. For this example we are going to invoice our customer with NET 7 payment terms each billing cycle. You could just as easily use AutoPay, which will charge your customer's payment source automatically when invoices are issued on the account.

curl "https://api.invoiced.com/customers" \
  -u {API_KEY}: \
  -d name="Acme" \
  -d email="billing@acmecorp.com" \
  -d number="1234" \
  -d payment_terms="NET 7"
require "invoiced"
invoiced = Invoiced::Client.new("{YOUR_API_KEY}")

customer = invoiced.Customer.create(
  :name => "Acme",
  :email => "billing@acmecorp.com",
  :number => "1234",
  :payment_terms => "NET 7"
)
$invoiced = new Invoiced\Client("{YOUR_API_KEY}");

$customer = $invoiced->Customer->create([
  'name' => "Acme",
  'email' => "billing@acmecorp.com",
  'number' => "1234",
  'payment_terms' => "NET 7"
]);
import invoiced
client = invoiced.Client("{YOUR_API_KEY}")

customer = client.Customer.create(
  name="Acme",
  email="billing@acmecorp.com",
  number="1234",
  payment_terms="NET 7"
)
import com.invoiced.entity.Connection;
import com.invoiced.entity.Customer;

Connection invoiced = new Connection("{YOUR_API_KEY}", false);

Customer customer = invoiced.newCustomer();
customer.name = "Acme";
customer.email = "billing@acmecorp.com";
customer.paymentTerms = "NET 7";
customer.create();

Subscribe the customer to a plan

In this example we are going to bill for charges that happen during our customer's billing cycle, in addition to the base subscription price. The plan we are using was created through the dashboard in Settings > Plans with the ID starter.

curl "https://api.invoiced.com/subscriptions" \
  -u {API_KEY}: \
  -d customer={CUSTOMER_ID} \
  -d plan="starter"
invoiced.Subscription.create(
    :customer => customer.id,
    :plan => "starter"
)
$invoiced->Subscription->create([
    'customer' => $customer->id,
    'plan' => "starter"
]);
client.Subscription.create(
    customer=customer.id,
    plan="starter"
)
import com.invoiced.entity.Subscription;

Subscription subscription = invoiced.newSubscription();
subscription.customer = customer.id;
subscription.plan = "starter";
subscription.create();

Add metered charges

Let's pretend during the billing cycle our customer used engineering hours that we want to bill for. Instead of issuing a separate invoice we can just add it to their next subscription invoice.

We are going to use an item from our catalog that was set up in Settings > Catalog with the ID engineer_hours. The catalog item already has the price set, however, you can also bill for line items not in your catalog, just like with invoices. The Line Item Object shows all of the attributes that we support for creating line items.

curl "https://api.invoiced.com/customers/{CUSTOMER_ID}/line_items" \
  -u {API_KEY}: \
  -d catalog_item="engineer_hours" \
  -d quantity=5
customer.line_items.create(
    :catalog_item => "engineer_hours",
    :quantity => 5
)
$customer->lineItems()->create([
    'catalog_item' => "engineer_hours",
    'quantity' => 5
]);
customer.line_items().create(
    catalog_item="engineer_hours",
    quantity=5
)
import com.invoiced.entity.PendingLineItem;

PendingLineItem pendingCharge = customer.newPendingLineItem();
pendingCharge.catalogItem = "delivery";
pendingCharge.quantity = 5;
pendingCharge.create();

And that's it! You can add further pending line items to the customer, or even edit an existing pending line item. Next time the subscription renews, your pending line items will be added to the invoice.

Trigger invoice for metered charges (optional)

If your customer is not on a subscription, or you want to bill them now for pending line items, then you can manually trigger an invoice for metered charges.

curl "https://api.invoiced.com/customers/{CUSTOMER_ID}/invoices" \
  -u {API_KEY}: \
  -X POST
customer.invoice
$customer->invoice();
customer.invoice()
import com.invoiced.entity.Invoice;

Invoice invoice = customer.invoice();

A new invoice using your customer's pending line items will be generated on the spot. If the customer does not have any pending line items then an error will be returned.

What's next?

We have gone through a basic metered billing workflow. Of course, business is not always that simple. The Metered Billing section of the API reference details all of the metered billing endpoints available to you.