API Reference
Introduction

18min
Hello! Invoiced is an API for billing customers and getting paid.
Our API was designed to handle all of the billing needs for your business or application while making the integration process as painless as possible. Through the API we can help you seamlessly manage invoicing, payments, subscription billing, metered billing, estimates, pricing, and much more.
We designed the Invoiced API around REST principles.
Here's a few pages that might be helpful in addition to this API reference.
﻿Sign up for Invoiced﻿
﻿Developer Documentation﻿
﻿Invoiced Sandbox﻿
API Endpoint
All API calls must be made to https://api.invoiced.com.
We also have a sandbox environment for testing available at https://api.sandbox.invoiced.com.
JSON-only
All responses will be in JSON. Input data passed through the request body can be form-encoded or JSON-encoded. If using a JSON body, please specify the Content-Type header as application/json.
In the API dates are represented as UNIX timestamps. Each entity like customers or invoices has a unique integer ID.
PDFs
A few endpoints support returning a PDF response instead of JSON if you set the Accept header to application/pdf. For example, the retrieve invoice endpoint can return a PDF. The endpoints that support PDFs are notated in the documentation.
Client Libraries
We have client libraries available in several languages. If you don't see your language listed then please contact us and we would be happy to help.
﻿.NET﻿
﻿Go﻿
﻿Java﻿
﻿PHP﻿
﻿Python﻿
﻿Ruby﻿
Getting Help or Contributing
We've made this document open source. Please report any issues or suggestions in the API doc issues. Any pull requests to improve this document are welcome too! If you need help using the API or need to discuss anything sensitive please message us at [email protected].
Authentication
The API uses HTTP Basic Authentication to authenticate users. A valid API key is required for all requests.
Obtaining an API Key
An API key can be obtained by signing in to invoiced.com, and then going to Settings → Developers → API Keys. Each business on Invoiced has its own set of API keys. We recommend creating a separate API key for each application that will be making calls on your behalf.
Usage
The API key must be passed in through the username with the password left blank. The right sidebar has an example request with authorization.
C#
Curl
Go
Java
PHP
Python
Ruby
import Invoiced;

var invoiced = new Connection("{YOUR_API_KEY}", Invoiced.Environment.production);
import Invoiced;

var invoiced = new Connection("{YOUR_API_KEY}", Invoiced.Environment.production);
﻿
Sandbox API
C#
Curl
Go
Java
PHP
Python
Ruby
import Invoiced;

var invoiced = new Connection("{YOUR_API_KEY}", Invoiced.Environment.sandbox);
import Invoiced;

var invoiced = new Connection("{YOUR_API_KEY}", Invoiced.Environment.sandbox);
﻿
You can sign up for a sandbox account at sandbox.invoiced.com and request an API key there. The steps for requesting an API key are the same as production.
Errors
Each API call returns an HTTP status code that reflects the nature of the response. We have done our best to follow the HTTP status code conventions.
Any request that did not succeed will return a 4xx or 5xx error. The 4xx range means there was a problem with the request, like a missing parameter. The 5xx range means that something went wrong on our end.
The Invoiced API returns the following HTTP status codes:
200 OK -- Request succeeded
201 Created -- A resource was created
204 No Content -- Request succeeded but there is no response body
400 Bad Request -- Invalid request parameters
401 Unauthorized -- Incorrect or missing API key
403 Forbidden -- You do not have permission to view a resource or perform an action
404 Not Found -- The specified resource could not be found
429 Too Many Requests -- You're moving too fast! Slow down!
500 Internal Server Error -- There was a problem on our end
All error responses will contain an object with these attributes
Parameter
Description
type
Type of error, invalid_request or api
message
Explanation of the error
param
Available when a specific request parameter was responsible
Pagination
Text
Link: <https://api.invoiced.com/customers?page=3&per_page=10>; rel="self",
	  <https://api.invoiced.com/customers?page=1&per_page=10>; rel="first",
	  <https://api.invoiced.com/customers?page=2&per_page=10>; rel="previous",
	  <https://api.invoiced.com/customers?page=4&per_page=10>; rel="next",
	  <https://api.invoiced.com/customers?page=5&per_page=10>; rel="last"
Link: <https://api.invoiced.com/customers?page=3&per_page=10>; rel="self",
	  <https://api.invoiced.com/customers?page=1&per_page=10>; rel="first",
	  <https://api.invoiced.com/customers?page=2&per_page=10>; rel="previous",
	  <https://api.invoiced.com/customers?page=4&per_page=10>; rel="next",
	  <https://api.invoiced.com/customers?page=5&per_page=10>; rel="last"
﻿
All list operations will be paginated in similar fashion as the GitHub API. In most cases we will paginate requests returning more than 100 results. You can control pagination with the page and per_page parameters. Pages start at 1 and the first page will be returned if no page is specified.
When traversing the pages, we recommend using the Link and X-Total-Count headers. The Link header will return URLs that you can use to traverse the API without having to write your own. It's preferred to use the links from the API because it protects against future updates.
Versioning
Any future changes to the API will be versioned in order to maintain backwards compatibility with existing integrations.
Metadata
C#
Curl
Go
Java
PHP
Python
Ruby
Dictionary<string, string> params = new Dictionary<string, string>();
params["icp_number"] = "1234567890";
params["account_rep"] = "Jan";
var customer = invoiced.NewCustomer();
customer.Name = "Acme";
customer.Metadata = params;
customer.Create();
Dictionary<string, string> params = new Dictionary<string, string>();
params["icp_number"] = "1234567890";
params["account_rep"] = "Jan";
var customer = invoiced.NewCustomer();
customer.Name = "Acme";
customer.Metadata = params;
customer.Create();
﻿
Most Invoiced objects have a metadata attribute. This parameter allows you to store custom key-value data on supported objects.
There are many use cases for metadata. Any time you want to store custom, structured data on an object, like a Customer or Invoice, then metadata is a great fit. Metadata is only visible within the API and in the dashboard. Customers will not see this data unless you choose to display it with a custom field.
Our custom fields feature is backed by the metadata store. If you are using custom fields then be sure to use the ID of your custom field as the key for your metadata value in order to link it with the right custom field. Custom fields are not required in order to use metadata.
Metadata can include up to 10 keys per object. Each key can be up to 40 characters long and values may be up to 255 characters long.
Special Parameters
Expanding Relations
C#
Curl
Go
Java
PHP
Python
Ruby
Dictionary<string, string> params = new Dictionary<string, string>();
params["expand"] = "customer";
var invoice = invoiced.NewInvoice().Retrieve("{INVOICE_ID}", params);
Dictionary<string, string> params = new Dictionary<string, string>();
params["expand"] = "customer";
var invoice = invoiced.NewInvoice().Retrieve("{INVOICE_ID}", params);
﻿
Usually you need to request more than just an invoice. Often, you might want data about the associated customer. There is a built-in way to do this that saves extra API requests.
Certain relational properties can be expanded by passing in a comma-separated list of properties to expand through the expand parameter. For example if you were requesting a payment and wanted to expand the associated customer and invoice objects you would set expand=customer,invoice. This will replace the ID on the customer and invoice properties with expanded objects.
The expand parameter works for any response that has relational properties.
Filter
Example retrieving a list of outstanding invoices for a customer:
C#
Curl
Go
Java
PHP
Python
Ruby
Dictionary<string, string> params = new Dictionary<string, string>();
params["filter[paid]"] = false;
params["filter[closed]"] = false;
params["filter[customer]"] = 1234;
var invoices = invoiced.NewInvoice().ListAll(params);
Dictionary<string, string> params = new Dictionary<string, string>();
params["filter[paid]"] = false;
params["filter[closed]"] = false;
params["filter[customer]"] = 1234;
var invoices = invoiced.NewInvoice().ListAll(params);
﻿
The filter parameter allows you to search entities based on an exact match. While it is not meant to replace a search API, the filter parameter can be useful if you need to look up a customer by name or want to list all overdue invoices. It can be used on many of the list endpoints.
The filter parameter is an object whose keys are the properties that should be matched.
Metadata Filter
Example retrieving customers with a matching account-rep metadata value:
C#
Curl
Go
Java
PHP
Python
Ruby
Dictionary<string, string> params = new Dictionary<string, string>();
params["metadata[account-rep]"] = "Jan";
var customers = invoiced.NewCustomer().ListAll(params);
Dictionary<string, string> params = new Dictionary<string, string>();
params["metadata[account-rep]"] = "Jan";
var customers = invoiced.NewCustomer().ListAll(params);
﻿
The metadata parameter behaves in a similar fashion to the filter parameter. It allows you to search entities that have an exactly matching metadata value for each constraint given. It can be used on any of the list endpoints for objects that support metadata.
The metadata parameter is an object whose keys should exactly match the metadata of the objects returned. If an object does not have a metadata value for a given key then the object will not be included in the result set, with no error being thrown.
Parameter	Description
type	Type of error, invalid_request or api
message	Explanation of the error
param	Available when a specific request parameter was responsible
Did this page help you?
Invoices