Metered Billing

Metered billing on Invoiced allows you to bill customers for charges that occur during a billing cycle outside of their ordinary subscription. These charges are called pending line items. A pending line item is a Line Item that has been attached to a customer, but not billed yet. Pending line items will be swept up by the next invoice that is triggered for the customer. This happens automatically with subscription invoices or when triggering an invoice manually.

Create a pending line item

curl "https://api.invoiced.com/customers/:customer_id/line_items" \
  -u {API_KEY}: \
  -d catalog_item="delivery"

customer = invoiced.Customer.retrieve("{CUSTOMER_ID}")
customer.line_items.create(
  :catalog_item => "delivery"
)

<?php

$customer = $invoiced->Customer->retrieve("{CUSTOMER_ID}");
$customer->lineItems()->create([
  'catalog_item' => "delivery"
]);

customer = client.Customer.retrieve("{CUSTOMER_ID}")
customer.line_items().create(
  catalog_item="delivery"
)

Customer customer = invoiced.newCustomer().retrieve({CUSTOMER_ID});
PendingLineItem pli = customer.newPendingLineItem();
pli.item = "delivery";
pli.create();

var customer = invoiced.NewCustomer().Retrieve({CUSTOMER_ID});
var pli = customer.NewPendingLineItem();
pli.Item = "delivery";
pli.Create();

pli, err := client.Customer.NewPendingLineItem({CUSTOMER_ID}, &invoiced.PendingLineItemRequest{
  Item: invoiced.String("delivery"),
})

The above command returns JSON structured like this:

{
    "amount": 10,
    "catalog_item": "delivery",
    "customer": 15444,
    "description": null,
    "discountable": true,
    "discounts": [],
    "id": 8,
    "metadata": [],
    "name": "Delivery",
    "object": "line_item",
    "quantity": 1,
    "taxable": true,
    "taxes": [],
    "type": "service",
    "unit_cost": 10,
    "updated_at": 1607152637
}

Create a new pending line item with this endpoint.

HTTP Request

POST /customers/:customer_id/line_items

Attributes

Parameter	Type	Description
catalog_item	string	Optional Item ID. Fills the line item with the name and pricing of the Item.
type	string	Optional line item type. Used to group line items by type in reporting
name	string	Title
description	string	Optional description
quantity	number	Quantity
unit_cost	number	Unit cost or rate
discountable	boolean	Excludes amount from invoice discounts when `false`, defaults to `true
discounts	array	Line item Discounts
taxable	boolean	Excludes amount from invoice taxes when `false`, defaults to `true
taxes	array	Line item Taxes
metadata	object	A hash of key/value pairs that can store additional information about this object.

Retrieve a pending line item

curl "https://api.invoiced.com/customers/:customer_id/line_items/:id" \
  -u {API_KEY}:

customer = invoiced.Customer.retrieve("{CUSTOMER_ID}")
line_item = customer.line_items.retrieve("{LINE_ITEM_ID}")

<?php

$customer = $invoiced->Customer->retrieve("{CUSTOMER_ID}");
$lineItem = $customer->lineItems()->retrieve("{LINE_ITEM_ID}");

customer = client.Customer.retrieve("{CUSTOMER_ID}")
line_item = customer.line_items().retrieve("{LINE_ITEM_ID}")

Customer customer = invoiced.newCustomer().retrieve({CUSTOMER_ID});
PendingLineItem pli = customer.newPendingLineItem().retrieve({LINE_ITEM_ID});

var customer = invoiced.NewCustomer().Retrieve({CUSTOMER_ID});
var pli = customer.NewPendingLineItem().Retrieve({LINE_ITEM_ID});

pli, err := client.Customer.RetrievePendingLineItem({CUSTOMER_ID}, {LINE_ITEM_ID})

The above command returns JSON structured like this:

{
    "amount": 10,
    "catalog_item": "delivery",
    "customer": 15444,
    "description": null,
    "discountable": true,
    "discounts": [],
    "id": 8,
    "metadata": [],
    "name": "Delivery",
    "object": "line_item",
    "quantity": 1,
    "taxable": true,
    "taxes": [],
    "type": "service",
    "unit_cost": 10,
    "updated_at": 1607152637
}

This endpoint retrieves a specific pending line item.

HTTP Request

GET /customers/:customer_id/line_items/:id

Update a pending line item

curl "https://api.invoiced.com/customers/:customer_id/line_items/:id" \
  -u {API_KEY}: \
  -d quantity=2 \
  -X PATCH

line_item.quantity = 2
line_item.save

<?php

$lineItem->quantity = 2;
$lineItem->save();

line_item.quantity = 2
line_item.save()

PendingLineItem pli = customer.newPendingLineItem().retrieve({LINE_ITEM_ID});
pli.quantity = 2;
pli.save();

var pli = customer.NewPendingLineItem().Retrieve({LINE_ITEM_ID});
pli.Quantity = 2;
pli.SaveAll();

pli, err = client.Customer.UpdatePendingLineItem({CUSTOMER_ID}, {LINE_ITEM_ID}, &invoiced.LineItemRequest{
  Quantity: invoiced.Float64(2),
})

The above command returns JSON structured like this:

{
    "amount": 20,
    "catalog_item": "delivery",
    "customer": 15444,
    "description": null,
    "discountable": true,
    "discounts": [],
    "id": 8,
    "metadata": [],
    "name": "Delivery",
    "object": "line_item",
    "quantity": 2,
    "taxable": true,
    "taxes": [],
    "type": "service",
    "unit_cost": 10,
    "updated_at": 1607152637
}

Use this endpoint to update a pending line item.

HTTP Request

PATCH /customers/:customer_id/line_items/:id

Request Parameters

Parameter	Type	Description
type	string	Optional line item type. Used to group line items by type in reporting
name	string	Title
description	string	Optional description
quantity	number	Quantity
unit_cost	number	Unit cost or rate
discountable	boolean	Excludes amount from invoice discounts when `false`, defaults to `true
discounts	array	Line item Discounts
taxable	boolean	Excludes amount from invoice taxes when `false`, defaults to `true
taxes	array	Line item Taxes
metadata	object	A hash of key/value pairs that can store additional information about this object.

Trigger an invoice

curl "https://api.invoiced.com/customers/:customer_id/invoices" \
  -u {API_KEY}: \
  -X POST

invoice = customer.invoice

<?php

$invoice = $customer->invoice();

invoice = customer.invoice()

Invoice invoice = customer.invoice();

var invoice = customer.Invoice();

invoice, err := client.Customer.TriggerInvoice({CUSTOMER_ID})

The above command returns JSON structured like this:

{
    "attempt_count": 0,
    "autopay": false,
    "balance": 51.15,
    "closed": false,
    "created_at": 1415229884,
    "currency": "usd",
    "customer": 15444,
    "date": 1416290400,
    "discounts": [],
    "draft": false,
    "due_date": 1417500000,
    "id": 46225,
    "items": [
        {
            "amount": 45,
            "catalog_item": null,
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 7,
            "metadata": [],
            "name": "Copy Paper, Case",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "product",
            "unit_cost": 45
        },
        {
            "amount": 10,
            "catalog_item": "delivery",
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 8,
            "metadata": [],
            "name": "Delivery",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "service",
            "unit_cost": 10
        }
    ],
    "metadata": [],
    "name": null,
    "next_payment_attempt": null,
    "notes": null,
    "number": "INV-0016",
    "object": "invoice",
    "paid": false,
    "payment_terms": "NET 14",
    "payment_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/payment",
    "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "status": "not_sent",
    "subscription": null,
    "subtotal": 55,
    "taxes": [
        {
            "amount": 3.85,
            "id": 20554,
            "object": "tax",
            "tax_rate": null
        }
    ],
    "total": 51.15,
    "updated_at": 1415229884,
    "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY"
}

This endpoint generates an invoice for a customer with its pending line items.

HTTP Request

POST /customers/:customer_id/invoices

Delete a pending line item

curl "https://api.invoiced.com/customers/:customer_id/line_items/:id" \
  -u {API_KEY}: \
  -X DELETE

line_item.delete

<?php

$lineItem->delete();

line_item.delete()

PendingLineItem pli = customer.newPendingLineItem().retrieve({LINE_ITEM_ID});
pli.delete();

var pli = customer.NewPendingLineItem().Retrieve({LINE_ITEM_ID});
pli.Delete();

err := client.Customer.DeletePendingLineItem({CUSTOMER_ID}, {LINE_ITEM_ID})

The above command returns 204 No Content

This endpoint deletes a specific pending line item.

HTTP Request

DELETE /customers/:customer_id/line_items/:id

List all pending line items

curl "https://api.invoiced.com/customers/:customer_id/line_items" \
  -u {API_KEY}:

customer = invoiced.Customer.retrieve("{CUSTOMER_ID}")
line_items, metadata = customer.line_items.list(:per_page => 3)

<?php

$customer = $invoiced->Customer->retrieve("{CUSTOMER_ID}");
list($lineItems, $metadata) = $customer->lineItems()->all(['per_page' => 3]);

customer = client.Customer.retrieve("{CUSTOMER_ID}")
line_items, metadata = customer.line_items().list(per_page=3)

PendingLineItem pli = customer.newPendingLineItem();
EntityList<PendingLineItem> plis = pli.listAll();

var plis = customer.NewPendingLineItem().ListAll();

plis, err := client.Customer.ListAllPendingLineItems({CUSTOMER_ID})

The above command returns JSON structured like this:

[
  {
     "amount": 10,
     "catalog_item": "delivery",
     "customer": 15444,
     "description": null,
     "discountable": true,
     "discounts": [],
     "id": 8,
     "metadata": [],
     "name": "Delivery",
     "object": "line_item",
     "quantity": 1,
     "taxable": true,
     "taxes": [],
     "type": "service",
     "unit_cost": 10,
     "updated_at": 1607152637
 }
]

This endpoint retrieves all pending line items.

HTTP Request

GET /customers/:customer_id/line_items

Query Parameters

Parameter	Description
sort string	Column to sort by, i.e. `name asc`
filter object	Filter object
metadata object	Metadata filter object