Developing on Invoiced
8min
at the heart of invoiced is a powerful billing api it allows you to build integrations with accounting systems, crms, ordering systems, business intelligence, and any other backoffice systems used to run your business communication with the rest api happens with https //api invoiced com if you are using the sandbox environment https //docs invoiced com/getting started/testing then the api endpoint is https //api sandbox invoiced com this document will walk you through a common invoicing workflow you can also dive into the api reference https //developer invoiced com/api to see all of the available api endpoints getting started the first step is to determine how you want to connect to the api we offer client libraries in several languages, including ruby, php, python, java, net, and go if we don't have a client library for your language then you can perform the http requests to invoiced directly in the language of your choice once you have your client library ready to go the next step is to get an api key the api uses basic authentication https //en wikipedia org/wiki/basic access authentication to authenticate requests all api requests require a valid api key you can grab an api key by signing in to the dashboard, and then going to settings → developers → api keys please remember to keep this api key safe in the wrong hands it could give unwanted access to your invoiced account next, we are going to walk through a common invoicing workflow creating a customer customers are at the core of everything on invoiced customers represent a billable entity from your perspective, whether this is a person, organization, or account you must create a customer first before you can invoice or accept payments every customer has an autopay https //docs invoiced com/payments/autopay option when enabled this will charge your customer's connected payment source each billing cycle when autopay is off (the default) we will instead issue an invoice that your customer can pay using any of the payment methods you accept curl "https //api invoiced com/customers" \\ u {api key} \\ d name="acme" \\ d email="billing\@acmecorp com" \\ d number="1234" \\ d payment terms="net 30"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 30"; customer create();$invoiced = new invoiced\client("{your api key}"); $customer = $invoiced >customer >create(\[ 'name' => "acme", 'email' => "billing\@acmecorp com", 'number' => "1234", 'payment terms' => "net 30" ]);import invoiced client = invoiced client("{your api key}") customer = client customer create( name="acme", email="billing\@acmecorp com", number="1234", payment terms="net 30" )require "invoiced" invoiced = invoiced client new("{your api key}") customer = invoiced customer create( \ name => "acme", \ email => "billing\@acmecorp com", \ number => "1234", \ payment terms => "net 30" ) the number property helps you tie the customer on invoiced to the id already used within your system it is not required as we would generate a value for you if it was not supplied we highly recommend saving the customer's invoiced id ( id property) in your own database this id is required to retrieve the customer's account, create invoices, and perform any other customer centric tasks creating an invoice invoices are another core resource on invoiced as you would expect, an invoice represents an amount owed to you by a customer curl "https //api invoiced com/invoices" \\ u {api key} \\ d customer={customer id} \\ d items\[0]\[name]="copy paper, case" \\ d items\[0]\[quantity]=3 \\ d items\[0]\[unit cost]=45 \\ d items\[1]\[name]="delivery" \\ d items\[1]\[quantity]=1 \\ d items\[1]\[unit cost]=10 \\ d taxes\[0]\[amount]=3 85import com invoiced entity invoice; import com invoiced entity lineitem; import com invoiced entity tax; invoice invoice = invoiced newinvoice(); invoice customer = customer id; invoice paymentterms = "net 14"; lineitem\[] items = new lineitem\[2]; items\[0] = new lineitem(); items\[0] name = "copy paper, case"; items\[0] quantity = 3d; items\[0] unitcost = 45d; items\[1] = new lineitem(); items\[1] name = "delivery"; items\[1] quantity = 1d; items\[1] unitcost = 10d; invoice items = items; tax\[] taxes = new tax\[1]; taxes\[0] = new tax(); taxes\[0] amount = 3 85d; invoice taxes = taxes; invoice create();\<?php $invoice = $invoiced >invoice >create(\[ 'customer' => $customer >id, 'items' => \[ \[ 'name' => "copy paper, case", 'quantity' => 3, 'unit cost' => 45 ], \[ 'name' => "delivery", 'quantity' => 1, 'unit cost' => 10 ] ], 'taxes' => \[ \[ 'amount' => 3 85 ] ] ]);invoice = client invoice create( customer=customer id, items=\[ { 'name' "copy paper, case", 'quantity' 3, 'unit cost' 45 }, { 'name' "delivery", 'quantity' 1, 'unit cost' 10 } ], taxes=\[ { 'amount' 3 85 } ] )invoice = invoiced invoice create( \ customer => customer id, \ items => \[ { \ name => "copy paper, case", \ quantity => 3, \ unit cost => 45 }, { \ name => "delivery", \ quantity => 1, \ unit cost => 10 } ], \ taxes => \[ { \ amount => 3 85 } ] ) the invoice will inherit the autopay and payment term settings from the customer's profile sending invoices now that you have created the invoice you might want to send it to the customer that's fairly easy to do through the api curl "https //api invoiced com/invoices/{invoice id}/emails" \\ u {api key} \\ x postimport com invoiced entity email; import com invoiced entity emailrequest; emailrequest emailrequest = new emailrequest(); email\[] emails = invoice send(emailrequest);$invoice >send();invoice sendinvoice send the customer will be sent the invoice with a view invoice button using the default email template you can customize these templates through the dashboard in settings → emails items our items feature allows you to build a simpler, more robust integration by centralizing pricing information for the products and services that you sell you must first add items through the dashboard in settings → items or through the items api then you can bill for items by simply referencing them by id curl "https //api invoiced com/invoices" \\ u {api key} \\ d customer={customer id} \\ d items\[0]\[catalog item]="copy paper 20lb" \\ d items\[0]\[quantity]=3 \\ d items\[1]\[catalog item]="delivery" \\ d taxes\[0]\[amount]=3 85import com invoiced entity invoice; import com invoiced entity lineitem; import com invoiced entity tax; invoice invoice = invoiced newinvoice(); invoice customer = customer id; invoice paymentterms = "net 14"; lineitem\[] items = new lineitem\[2]; items\[0] = new lineitem(); items\[0] catalogitem = "copy paper 20lb"; items\[0] quantity = 3d; items\[1] = new lineitem(); items\[1] catalogitem = "delivery"; invoice items = items; tax\[] taxes = new tax\[1]; taxes\[0] = new tax(); taxes\[0] amount = 3 85d; invoice taxes = taxes; invoice create();\<?php $invoice = $invoiced >invoice >create(\[ 'customer' => $customer >id, 'items' => \[ \[ 'catalog item' => 'copy paper 20lb', 'quantity' => 3 ], \[ 'catalog item' => "delivery" ] ], 'taxes' => \[ \[ 'amount' => 3 85 ] ] ]);invoice = client invoice create( customer=customer id, items=\[ { 'catalog item' "copy paper 20lb", 'quantity' 3 }, { 'catalog item' "delivery" } ], taxes=\[ { 'amount' 3 85 } ] )invoiced invoice create( \ customer => customer id, \ items => \[ { \ catalog item => "copy paper 20lb", \ quantity => 3 }, { \ catalog item => "delivery" } ], \ taxes => \[ { \ amount => 3 85 } ] ) note that we did not have to include the unit cost on the item as it was filled in automatically (although you can override per line item by including it) another benefit of items is that it ties line items together in reports recording a payment on invoiced payments are represent with the payment resource a payment models the exchange of value between you and a customer, including payments, refunds, and credits whenever customers pay online through the customer portal we automatically create a payment however, if you accept payments outside of invoiced, always true if you are accepting checks or wire transfers, then you have to record the payment yourself through the dashboard or api curl "https //api invoiced com/payments" \\ u {api key} \\ d applied to\[type]="invoice" \\ d applied to\[invoice]={invoice id} \\ d method="check" \\ d reference="1450" \\ d amount=148 85import com invoiced entity transaction; transaction transaction = invoiced newtransaction(); transaction invoice = invoice id; transaction method = "check"; transaction gatewayid = "1450"; transaction amount = 148 85; transaction create();\<?php $invoiced >transaction >create(\[ 'invoice' => $invoice >id, 'method' => "check", 'gateway id' => "1450", 'amount' => 148 85 ]);client transaction >create( invoice=invoice id, method="check", gateway id="1450", amount=148 85 )invoiced transaction create( \ invoice => invoice id, \ method => "check", \ gateway id => "1450", \ amount => 148 85 ) this will record a payment for the invoice we created earlier and mark it as paid since this is an offline payment, the reference property can be used to reference a check # and that's it for a basic accounts receivable workflow what's next? the api reference https //developer invoiced com/api explains all of the resources and endpoints available to you our other development guides might be useful as well if you run into any questions or need help with some code then please don't hesitate to contact us we would love to hear from you