Developing on Invoiced
Metered Billing
9min
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 automatically at the end of a customer's billing period any pending line items will be swept up into the next subscription invoice 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 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 https //docs invoiced com/payments/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"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();$invoiced = new invoiced\client("{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" ]);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" ) 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"import com invoiced entity subscription; subscription subscription = invoiced newsubscription(); subscription customer = customer id; subscription plan = "starter"; subscription create();$invoiced >subscription >create(\[ 	'customer' => $customer >id, 	'plan' => "starter" ]);client subscription create( 	customer=customer id, 	plan="starter" )invoiced subscription create( 	\ customer => customer id, 	\ plan => "starter" ) 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 that was set up in settings → items with the id engineer hours the item already has the price set, however, you can also bill for one off line items, just like with invoices the line item object https //developer invoiced com/api/invoices#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=5import com invoiced entity pendinglineitem; pendinglineitem pendingcharge = customer newpendinglineitem(); pendingcharge catalogitem = "delivery"; pendingcharge quantity = 5; pendingcharge create();$customer >lineitems() >create(\[ 	'catalog item' => "engineer hours", 	'quantity' => 5 ]);customer line items() create( 	catalog item="engineer hours", 	quantity=5 )customer line items create( 	\ catalog item => "engineer hours", 	\ quantity => 5 ) 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 postimport com invoiced entity invoice; invoice invoice = customer invoice();$customer >invoice();customer 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 https //invoiced com/docs/api/#metered billing section of the api reference details all of the metered billing endpoints available to you