NAV
shell ruby php

Introduction

Invoiced is simple invoicing for freelancers and small businesses. Our HTTP API was designed to be easy to integrate into your workflow.

We have done our best to follow REST principles when designing the API.

API Endpoint

All API calls must be made to https://api.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.

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.

Getting Help or Contributing

We’ve made this document open source. Please report any issues or suggestions in the issues. If you need help using the API or need to discuss anything sensitive please message us at api@invoiced.com. Any pull requests to improve this document are welcome too!

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 > 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

curl https://api.invoiced.com/invoices \
  -u {YOUR_API_KEY}:
require "invoiced"
invoiced = Invoiced::Client.new("{YOUR_API_KEY}")
<?php

$invoiced = new Invoiced\Client("{YOUR_API_KEY}");

The API key must be passed in through the username with the password left blank. The right sidebar has an example request with authorization

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

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.

Special Parameters

Expanding Relations

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

"filter": {
    "paid": false,
    "customer": 1234
}
:filter => {
  :paid => false,
  :customer => 1234
}
"filter" => [
  "paid" => false,
  "customer" => 1234
]

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:

Customers

Customers represent the entity you are billing, whether this is an organization or a individual. Each customer has a collection mode, automatic or manual. In automatic collection mode any invoices will be charged to your customer’s payment source. Currently we only support debit and credit cards as payment sources.

Conversely, manual collection mode will let your customers pay each invoice issued with one of the payment methods you accept.

Customer Object

Attributes

{
  "id": 15444,
  "name": "Acme",
  "number": "CUST-0001",
  "email": "billing@acmecorp.com",
  "type": "company",
  "collection_mode": "auto",
  "payment_terms": null,
  "payment_source": {
    "id": 850,
    "brand": "Visa",
    "last4": 4242,
    "exp_month": 2,
    "exp_year": 20,
    "funding": "credit"
  },
  "attention_to": null,
  "address1": null,
  "address2": null,
  "city": null,
  "state": null,
  "postal_code": null,
  "country": "United States",
  "tax_id": null,
  "phone": null,
  "other_phone": null,
  "website": null,
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}
#<Invoiced::Customer:0x3fdbf95e4d08 id=15444> JSON: {
  "id": 15444,
  "name": "Acme",
  "number": "CUST-0001",
  "email": "billing@acmecorp.com",
  "type": "company",
  "collection_mode": "auto",
  "payment_terms": null,
  "payment_source": {
    "id": 850,
    "brand": "Visa",
    "last4": 4242,
    "exp_month": 2,
    "exp_year": 20,
    "funding": "credit"
  },
  "attention_to": null,
  "address1": null,
  "address2": null,
  "city": null,
  "state": null,
  "postal_code": null,
  "country": "United States",
  "tax_id": null,
  "phone": null,
  "other_phone": null,
  "website": null,
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}
Invoiced\Customer JSON: {
  "id": 15444,
  "name": "Acme",
  "number": "CUST-0001",
  "email": "billing@acmecorp.com",
  "type": "company",
  "collection_mode": "auto",
  "payment_terms": null,
  "payment_source": {
    "id": 850,
    "brand": "Visa",
    "last4": 4242,
    "exp_month": 2,
    "exp_year": 20,
    "funding": "credit"
  },
  "attention_to": null,
  "address1": null,
  "address2": null,
  "city": null,
  "state": null,
  "postal_code": null,
  "country": "United States",
  "tax_id": null,
  "phone": null,
  "other_phone": null,
  "website": null,
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}
Parameter Type Description
id integer The customer’s unique ID
name string Customer name
number string The reference number assigned to the customer for use in the dashboard
type string Organization type, company or person
email string Email address
collection_mode string Invoice collection mode, auto or manual
payment_terms string Payment terms used for manual collection mode, i.e. “NET 30”
payment_source object Summary of the customer’s payment source, if attached
attention_to string Used for ATTN: address line if company
address1 string First address line
address2 string Optional second address line
city string City
state string State or province
postal_code string Zip or postal code
country string Country
tax_id string Tax ID to be displayed on documents
phone string Phone #
other_phone string Second phone #
website string Website
notes string Private customer notes
statement_pdf_url string URL to download the latest account statement
created_at timestamp Timestamp when created

Create a customer

curl "https://api.invoiced.com/customers" \
  -u {API_KEY}: \
  -d name="Acme" \
  -d email="billing@acmecorp.com" \
  -d collection_mode="manual" \
  -d payment_terms="NET 30" \
  -d type="company"
invoiced.Customer.create(
  :name => "Acme",
  :email => "billing@acmecorp.com",
  :collection_mode => "manual",
  :payment_terms => "NET 30",
  :type => "company"
)
<?php

$invoiced->Customer->create([
  'name' => "Acme",
  'email' => "billing@acmecorp.com",
  'collection_mode' => "manual",
  'payment_terms' => "NET 30",
  'type' => "company"
]);

The above command returns JSON structured like this:

{
  "id": 15444,
  "number": "CUST-0001",
  "name": "Acme",
  "email": "billing@acmecorp.com",
  "collection_mode": "manual",
  "payment_terms": "NET 30",
  "payment_source": null,
  "type": "company",
  "attention_to": null,
  "address1": null,
  "address2": null,
  "city": null,
  "state": null,
  "postal_code": null,
  "country": "United States",
  "tax_id": null,
  "phone": null,
  "other_phone": null,
  "website": null,
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}
#<Invoiced::Customer:0x3fdbf95e4d08 id=15444> JSON: {
  "id": 15444,
  "number": "CUST-0001",
  "name": "Acme",
  "email": "billing@acmecorp.com",
  "collection_mode": "manual",
  "payment_terms": "NET 30",
  "payment_source": null,
  "type": "company",
  "attention_to": null,
  "address1": null,
  "address2": null,
  "city": null,
  "state": null,
  "postal_code": null,
  "country": "United States",
  "tax_id": null,
  "phone": null,
  "other_phone": null,
  "website": null,
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}
Invoiced\Customer JSON: {
  "id": 15444,
  "number": "CUST-0001",
  "name": "Acme",
  "email": "billing@acmecorp.com",
  "collection_mode": "manual",
  "payment_terms": "NET 30",
  "payment_source": null,
  "type": "company",
  "attention_to": null,
  "address1": null,
  "address2": null,
  "city": null,
  "state": null,
  "postal_code": null,
  "country": "United States",
  "tax_id": null,
  "phone": null,
  "other_phone": null,
  "website": null,
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}

Create a new customer profile with this endpoint.

HTTP Request

POST /customers

Attributes

Parameter Type Description
name string Customer name - required
number string The reference number assigned to the customer for use in the dashboard. We will generate one if not supplied.
type string Organization type, company or person. Defaults to company
email string Email address
collection_mode string Invoice collection mode, auto or manual. Defaults to manual
payment_terms string Payment terms used for manual collection mode, i.e. “NET 30”
stripe_token string When provided sets the customer’s payment source to the tokenized Stripe card
attention_to string Used for ATTN: address line if company
address1 string First address line
address2 string Optional second address line
city string City
state string State or province
postal_code string Zip or postal code
country string Country
tax_id string Tax ID to be displayed on documents
phone string Phone #
other_phone string Second phone #
website string Website
notes string Private customer notes

Retrieve a customer

curl "https://api.invoiced.com/customers/:id" \
  -u {API_KEY}:
customer = invoiced.Customer.retrieve("{CUSTOMER_ID}")
<?php

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

The above command returns JSON structured like this:

{
  "id": 15444,
  "number": "CUST-0001",
  "name": "Acme",
  "email": "billing@acmecorp.com",
  "collection_mode": "manual",
  "payment_terms": "NET 30",
  "payment_source": null,
  "type": "company",
  "attention_to": "Sarah Fisher",
  "address1": "342 Amber St",
  "address2": null,
  "city": "Hill Valley",
  "state": "CA",
  "postal_code": "94523",
  "country": "United States",
  "tax_id": "893-934835",
  "phone": "(820) 297-2983",
  "other_phone": null,
  "website": "acmecorp.com",
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}
#<Invoiced::Customer:0x3fdbf95e4d08 id=15444> JSON: {
  "id": 15444,
  "number": "CUST-0001",
  "name": "Acme",
  "email": "billing@acmecorp.com",
  "collection_mode": "manual",
  "payment_terms": "NET 30",
  "payment_source": null,
  "type": "company",
  "attention_to": null,
  "address1": null,
  "address2": null,
  "city": null,
  "state": null,
  "postal_code": null,
  "country": "United States",
  "tax_id": null,
  "phone": null,
  "other_phone": null,
  "website": null,
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}
Invoiced\Customer JSON: {
  "id": 15444,
  "number": "CUST-0001",
  "name": "Acme",
  "email": "billing@acmecorp.com",
  "collection_mode": "manual",
  "payment_terms": "NET 30",
  "payment_source": null,
  "type": "company",
  "attention_to": null,
  "address1": null,
  "address2": null,
  "city": null,
  "state": null,
  "postal_code": null,
  "country": "United States",
  "tax_id": null,
  "phone": null,
  "other_phone": null,
  "website": null,
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}

This endpoint retrieves a specific customer.

HTTP Request

GET /customers/:id

Update a customer

curl "https://api.invoiced.com/customers/:id" \
  -u {API_KEY}: \
  -d payment_terms="NET 14" \
  -d attention_to="Sarah Fisher" \
  -d address1="342 Amber St" \
  -d city="Hill Valley" \
  -d state="CA" \
  -d postal_code="94523" \
  -d tax_id="893-934835" \
  -d phone="(820) 297-2983" \
  -d website="acmecorp.com" \
  -X PATCH
customer.payment_terms = "NET 14"
customer.attention_to = "Sarah Fisher"
customer.address1 = "342 Amber St"
customer.city = "Hill Valley"
customer.state = "CA"
customer.postal_code = "94523"
customer.tax_id = "893-934835"
customer.phone = "(820) 297-2983"
customer.website = "acmecorp.com"
customer.save
<?php

$customer->payment_terms = "NET 14";
$customer->attention_to = "Sarah Fisher";
$customer->address1 = "342 Amber St";
$customer->city = "Hill Valley";
$customer->state = "CA";
$customer->postal_code = "94523";
$customer->tax_id = "893-934835";
$customer->phone = "(820) 297-2983";
$customer->website = "acmecorp.com";
$customer->save();

The above command returns JSON structured like this:

{
  "id": 15444,
  "number": "CUST-0001",
  "name": "Acme",
  "email": "billing@acmecorp.com",
  "collection_mode": "manual",
  "payment_terms": "NET 14",
  "payment_source": null,
  "type": "company",
  "attention_to": "Sarah Fisher",
  "address1": "342 Amber St",
  "address2": null,
  "city": "Hill Valley",
  "state": "CA",
  "postal_code": "94523",
  "country": "United States",
  "tax_id": "893-934835",
  "phone": "(820) 297-2983",
  "other_phone": null,
  "website": "acmecorp.com",
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}
#<Invoiced::Customer:0x3fdbf95e4d08 id=15444> JSON: {
  "id": 15444,
  "number": "CUST-0001",
  "name": "Acme",
  "email": "billing@acmecorp.com",
  "collection_mode": "manual",
  "payment_terms": "NET 14",
  "payment_source": null,
  "type": "company",
  "attention_to": "Sarah Fisher",
  "address1": "342 Amber St",
  "address2": null,
  "city": "Hill Valley",
  "state": "CA",
  "postal_code": "94523",
  "country": "United States",
  "tax_id": "893-934835",
  "phone": "(820) 297-2983",
  "other_phone": null,
  "website": "acmecorp.com",
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}
Invoiced\Customer JSON: {
  "id": 15444,
  "number": "CUST-0001",
  "name": "Acme",
  "email": "billing@acmecorp.com",
  "collection_mode": "manual",
  "payment_terms": "NET 14",
  "payment_source": null,
  "type": "company",
  "attention_to": "Sarah Fisher",
  "address1": "342 Amber St",
  "address2": null,
  "city": "Hill Valley",
  "state": "CA",
  "postal_code": "94523",
  "country": "United States",
  "tax_id": "893-934835",
  "phone": "(820) 297-2983",
  "other_phone": null,
  "website": "acmecorp.com",
  "notes": null,
  "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
  "created_at": 1415222128
}

Use this endpoint to update a customer profile.

HTTP Request

PATCH /customers/:id

Request Parameters

Parameter Type Description
name string Customer name
number string The reference number assigned to the customer for use in the dashboard
type string Organization type, company or person
email string Email address
collection_mode string Invoice collection mode, auto or manual
payment_terms string Payment terms used for manual collection mode, i.e. “NET 30”
stripe_token string When provided sets the customer’s payment source to the tokenized Stripe card
attention_to string Used for ATTN: address line if company
address1 string First address line
address2 string Optional second address line
city string City
state string State or province
postal_code string Zip or postal code
country string Country
tax_id string Tax ID to be displayed on documents
phone string Phone #
other_phone string Second phone #
website string Website
notes string Private customer notes

List customer subscriptions

curl "https://api.invoiced.com/customers/:id/subscriptions" \
  -u {API_KEY}:
subscriptions, metadata = customer.subscriptions
<?php

list($subscriptions, $metadata) = $customer->subscriptions();

The above command returns JSON structured like this:

[
  {
      "id": 412,
      "customer": 15444,
      "plan": 418,
      "start_date": 1415230038,
      "quantity": 1,
      "cycles": null,
      "renews_next": 1438813638,
      "renewed_last": 1436135238,
      "status": "past_due",
      "url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ClfLz70YiFSgu5E2dA5qrwXX",
      "created_at": 1415230041
  },
  {
      "id": 595,
      "customer": 15444,
      "plan": 420,
      "start_date": 1425572792,
      "quantity": 1,
      "cycles": null,
      "renews_next": 1438788392,
      "renewed_last": 1436109992,
      "status": "active",
      "url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ir5n8vGRTcsJyBNS8lzR6gXX",
      "created_at": 1425572798
  }
]
[
  #<Invoiced::Subscription:0x3fdbf9sf9e4d08 id=412> JSON: {
      "id": 412,
      "customer": 15444,
      "plan": 418,
      "start_date": 1415230038,
      "quantity": 1,
      "cycles": null,
      "renews_next": 1438813638,
      "renewed_last": 1436135238,
      "status": "past_due",
      "url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ClfLz70YiFSgu5E2dA5qrwXX",
      "created_at": 1415230041
  },
  #<Invoiced::Subscription:0x3fdbf95as4d08 id=595> JSON: {
      "id": 595,
      "customer": 15444,
      "plan": 420,
      "start_date": 1425572792,
      "quantity": 1,
      "cycles": null,
      "renews_next": 1438788392,
      "renewed_last": 1436109992,
      "status": "active",
      "url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ir5n8vGRTcsJyBNS8lzR6gXX",
      "created_at": 1425572798
  }
]
[
  Invoiced\Subscription JSON: {
      "id": 412,
      "customer": 15444,
      "plan": 418,
      "start_date": 1415230038,
      "quantity": 1,
      "cycles": null,
      "renews_next": 1438813638,
      "renewed_last": 1436135238,
      "status": "past_due",
      "url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ClfLz70YiFSgu5E2dA5qrwXX",
      "created_at": 1415230041
  },
  Invoiced\Subscription JSON: {
      "id": 595,
      "customer": 15444,
      "plan": 420,
      "start_date": 1425572792,
      "quantity": 1,
      "cycles": null,
      "renews_next": 1438788392,
      "renewed_last": 1436109992,
      "status": "active",
      "url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ir5n8vGRTcsJyBNS8lzR6gXX",
      "created_at": 1425572798
  }
]

This endpoint lists all the subscriptions for a specific customer.

HTTP Request

GET /customers/:id/subscriptions

Query Parameters

Parameter Type Description
expand string Properties to expand

Get current balance

curl "https://api.invoiced.com/customers/balance" \
  -u {API_KEY}:
customer.balance
<?php

$customer->balance();

The above command returns JSON structured like this:

{
  "available_credits": 50,
  "past_due": false,
  "total_outstanding": 470
}
{
  :available_credits => 50,
  :past_due => false,
  :total_outstanding => 470
}
stdClass {
  "available_credits": 50,
  "past_due": false,
  "total_outstanding": 470
}

This endpoint calculates the customer’s current balance.

HTTP Request

GET /customers/:id/balance

Send a statement

curl "https://api.invoiced.com/customers/:id/emails" \
  -u {API_KEY}: \
  -X POST
emails = customer.send_statement
<?php

$emails = $customer->sendStatement();

The above command returns JSON structured like this:

[
  {
    "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
    "state": "sent",
    "reject_reason": null,
    "email": "client@example.com",
    "template": "statement_email",
    "subject": "Statement from Dunder Mifflin, Inc.",
    "message": "Dear Client, we have attached your latest account statement. Thank you!",
    "opens": 0,
    "opens_detail": [],
    "clicks": 0,
    "clicks_detail": [],
    "created_at": 1436890047
  },
  { ... },
  { ... }
]
[
  #<Invoiced::Email:0x3fdbf95e4d08 id="f45382c6fbc44d44aa7f9a55eb2ce731"> JSON: {
    "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
    "state": "sent",
    "reject_reason": null,
    "email": "client@example.com",
    "template": "statement_email",
    "subject": "Statement from Dunder Mifflin, Inc.",
    "message": "Dear Client, we have attached your latest account statement. Thank you!",
    "opens": 0,
    "opens_detail": [],
    "clicks": 0,
    "clicks_detail": [],
    "created_at": 1436890047
  },
  #<Invoiced::Email:0x3fdasdf95e09 id="a0s36fbc44d44aa7f9a55easdfi8ce731"> JSON: { ... },
  #<Invoiced::Email:0x3fdbffge4d10 id="s90f2c6fbc44sdfj8aa7f9a55eb2ce731"> JSON: { ... }
]
[
  Invoiced\Email JSON: {
    "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
    "state": "sent",
    "reject_reason": null,
    "email": "client@example.com",
    "template": "statement_email",
    "subject": "Statement from Dunder Mifflin, Inc.",
    "message": "Dear Client, we have attached your latest account statement. Thank you!",
    "opens": 0,
    "opens_detail": [],
    "clicks": 0,
    "clicks_detail": [],
    "created_at": 1436890047
  },
  Invoiced\Email JSON: { ... },
  Invoiced\Email JSON: { ... }
]

This endpoint sends a PDF account statement to a customer.

HTTP Request

POST /customers/:id/emails

Request Parameters

Parameter Type Description
to array Optional array of recipients like:
[{"name": "Client", "email": "client@example.com"}]
bcc string Optional comma-separated list of email addresses to be blind carbon copied
subject string Optional subject
message string Optional message body, otherwise the Statement Email template is used

Delete a customer

curl "https://api.invoiced.com/customers/:id" \
  -u {API_KEY}: \
  -X DELETE
customer.delete
<?php

$customer->delete();

The above command returns 204 No Content

This endpoint deletes a specific customer.

HTTP Request

DELETE /customers/:id

List all customers

curl "https://api.invoiced.com/customers" \
  -u {API_KEY}:
customers, metadata = invoiced.Customer.list(:per_page => 3)
<?php

list($customers, $metadata) = $invoiced->Customer->list(['per_page' => 3]);

The above command returns JSON structured like this:

[
  {
    "id": 15444,
    "number": "CUST-0001",
    "name": "Acme",
    "email": "billing@acmecorp.com",
    "collection_mode": "manual",
    "payment_terms": "NET 30",
    "payment_source": null,
    "type": "company",
    "attention_to": "Sarah Fisher",
    "address1": "342 Amber St",
    "address2": null,
    "city": "Hill Valley",
    "state": "CA",
    "postal_code": "94523",
    "country": "United States",
    "tax_id": "893-934835",
    "phone": "(820) 297-2983",
    "other_phone": null,
    "website": "acmecorp.com",
    "notes": null,
    "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
    "created_at": 1415222128
  },
  { ... },
  { ... }
]
[
  #<Invoiced::Customer:0x3fdbf95e4d08 id=15444> JSON: {
    "id": 15444,
    "number": "CUST-0001",
    "name": "Acme",
    "email": "billing@acmecorp.com",
    "collection_mode": "manual",
    "payment_terms": "NET 30",
    "payment_source": null,
    "type": "company",
    "attention_to": "Sarah Fisher",
    "address1": "342 Amber St",
    "address2": null,
    "city": "Hill Valley",
    "state": "CA",
    "postal_code": "94523",
    "country": "United States",
    "tax_id": "893-934835",
    "phone": "(820) 297-2983",
    "other_phone": null,
    "website": "acmecorp.com",
    "notes": null,
    "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
    "created_at": 1415222128
  },
  #<Invoiced::Customer:0x3fdbf95e4d09 id=15445> JSON: { ... },
  #<Invoiced::Customer:0x3fdbf95e4d10 id=15446> JSON: { ... }
]
[
  Invoiced\Customer JSON: {
    "id": 15444,
    "number": "CUST-0001",
    "name": "Acme",
    "email": "billing@acmecorp.com",
    "collection_mode": "manual",
    "payment_terms": "NET 30",
    "payment_source": null,
    "type": "company",
    "attention_to": "Sarah Fisher",
    "address1": "342 Amber St",
    "address2": null,
    "city": "Hill Valley",
    "state": "CA",
    "postal_code": "94523",
    "country": "United States",
    "tax_id": "893-934835",
    "phone": "(820) 297-2983",
    "other_phone": null,
    "website": "acmecorp.com",
    "notes": null,
    "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
    "created_at": 1415222128
  },
  Invoiced\Customer JSON: { ... },
  Invoiced\Customer JSON: { ... }
]

This endpoint retrieves all customers.

HTTP Request

GET /customers

Query Parameters

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

Invoices

An invoice representeds a balance owed to you by a Customer. Each invoice has a collection of line items that detail the products or services that are now due. An invoice can be in one of many different states depending on the due date, payments, and whether it was sent to or viewed by the customer.

Invoices can be marked as paid with Transactions. Once the sum of all Transactions for an invoice is greater than or equal to the total then the invoice will be considered paid in full.

Invoice Object

Attributes

{
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46225> JSON: {
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}
Invoiced\Invoice JSON: {
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}
Parameter Type Description
id integer The invoice’s unique ID
customer integer Customer ID
name string Invoice name for internal use, defaults to “Invoice”
number string The reference number assigned to the invoice for use in the dashboard
collection_mode string Invoice collection mode, auto or manual
currency string 3-digit ISO 4217 currency code
draft boolean When false, the invoice is considered outstanding, or when true, the invoice is a draft
sent boolean Indicates whether the invoice has been sent
closed boolean When true, an invoice is closed and considered bad debt. No further payments are allowed.
paid boolean Indicates whether an invoice has been paid in full
status string Invoice state, one of draft, not_sent, sent, viewed, past_due, pending, paid, or overpaid
chase boolean Whether chasing is enabled for the invoice
next_chase_on timestamp Next scheduled chase
attempt_count integer # of payment attempts
next_payment_attempt timestamp Next scheduled charge attempt, when in automatic collection
theme integer Theme ID for rendering with custom themes
subscription integer Subscription ID if invoice came from subscription
date timestamp Invoice date
due_date timestamp Date payment is due by
payment_terms string Payment terms for the invoice, i.e. “NET 30”
items array Collection of Line Item objects
terms string Terms and conditions displayed on invoice
notes string Additional notes displayed on invoice
subtotal number Subtotal
discounts array Collection of Discount objects
taxes array Collection of Tax objects
total number Total
balance number Balance
url string URL to view the invoice in the billing portal
pdf_url string URL to download the invoice as a PDF
created_at timestamp Timestamp when created

Line Item Object

Attributes

{
  "id": 8,
  "stored_item": null,
  "plan": null,
  "type": "service",
  "name": "Delivery",
  "description": "",
  "quantity": 1,
  "unit_cost": 10,
  "amount": 10,
  "discounts": [],
  "taxes": []
}
#<Invoiced::LineItem:0x3fdbf95e4d08 id=8> JSON: {
  "id": 8,
  "stored_item": null,
  "plan": null,
  "type": "service",
  "name": "Delivery",
  "description": "",
  "quantity": 1,
  "unit_cost": 10,
  "amount": 10,
  "discounts": [],
  "taxes": []
}
Invoiced\LineItem JSON: {
  "id": 8,
  "stored_item": null,
  "plan": null,
  "type": "service",
  "name": "Delivery",
  "description": "",
  "quantity": 1,
  "unit_cost": 10,
  "amount": 10,
  "discounts": [],
  "taxes": []
}
Parameter Type Description
id integer The line item’s unique ID
stored_item integer Stored Item ID this line is associated with, if any
plan integer Plan ID the line item was generated from
type string Line item type, one of product, service, hours, days, or expense
name string Title
description string Optional description
quantity number Quantity
unit_cost number Unit cost or rate
amount number Computed from quantity x unit_cost
discounts array Line item Discounts
taxes array Line item Taxes

Discount Object

Attributes

{
  "id": 20553,
  "amount": 5,
  "rate": null
}
#<Invoiced::Discount:0x3fdbf95e4d08 id=20553> JSON: {
  "id": 20553,
  "amount": 5,
  "rate": null
}
Invoiced\Discount JSON: {
  "id": 20553,
  "amount": 5,
  "rate": null
}
Parameter Type Description
id integer The discount’s unique ID
amount number Discount amount
rate object Discount Rate the discount was computed from, if any

Tax Object

Attributes

{
  "id": 20554,
  "amount": 3.85,
  "rate": null
}
#<Invoiced::Tax:0x3fdbf95e4d08 id=20554> JSON: {
  "id": 20554,
  "amount": 3.85,
  "rate": null
}
Invoiced\Tax JSON: {
  "id": 20554,
  "amount": 3.85,
  "rate": null
}
Parameter Type Description
id integer The tax’s unique ID
amount number Tax amount
rate object Tax Rate the tax was computed from, if any

Create an invoice

curl "https://api.invoiced.com/invoices" \
  -u {API_KEY}: \
  -d customer=15444 \
  -d payment_terms="NET 14" \
  -d items[0][name]="Copy paper, Case" \
  -d items[0][quantity]=1 \
  -d items[0][unit_cost]=45 \
  -d items[1][type]="service" \
  -d items[1][name]="Delivery" \
  -d items[1][quantity]=1 \
  -d items[1][unit_cost]=10 \
  -d taxes[0][amount]=3.85
invoiced.Invoice.create(
  :customer => 15444,
  :payment_terms => "NET 14",
  :items => [
    {
      :name => "Copy paper, Case",
      :quantity => 1,
      :unit_cost => 45
    },
    {
      :type => "service",
      :name => "Delivery",
      :quantity => 1,
      :unit_cost => 45
    }
  ],
  :taxes => [
    {
      :amount => 3.85
    }
  ]
)
<?php

$invoice = $invoiced->Invoice->create([
  'customer' => 15444,
  'payment_terms' => "NET 14",
  'items' => [
    [
      'name' => "Copy paper, Case",
      'quantity' => 1,
      'unit_cost' => 45
    ],
    [
      'type' => "service",
      'name' => "Delivery",
      'quantity' => 1,
      'unit_cost' => 45
    ]
  ],
  'taxes' => [
    [
      'amount' => 3.85
    ]
  ]
]);

The above command returns JSON structured like this:

{
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46225> JSON: {
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}
Invoiced\Invoice JSON: {
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}

Create a new invoice with this endpoint.

HTTP Request

POST /invoices

Attributes

Parameter Type Description
customer integer Customer ID - required
name string Invoice name for internal use, defaults to “Invoice”
number string The reference number assigned to the invoice, defaults to next # in auto-numbering sequence
currency string 3-digit ISO 4217 currency code - defaults to account currency
collection_mode string Invoice collection mode, auto or manual - inherited from customer by default
payment_terms string Payment terms for the invoice, i.e. “NET 30” - inherited from customer by default
date timestamp Invoice date - defaults to current timestamp
due_date timestamp Due date - computed from payment_terms when not supplied
draft boolean When false, the invoice is considered outstanding, or when true, the invoice is a draft
sent boolean Marks an invoice as sent
closed boolean Marks an invoice as closed
chase boolean Enables chasing for this invoice
theme integer Theme ID for rendering with custom themes
items array Collection of Line Item objects
terms string Terms and conditions displayed on invoice
notes string Additional notes displayed on invoice
discounts array Collection of Discount objects
taxes array Collection of Tax objects

Retrieve an invoice

curl "https://api.invoiced.com/invoices/:id" \
  -u {API_KEY}:
invoice = invoiced.Invoice.retrieve("{INVOICE_ID}")
<?php

$invoice = $invoiced->Invoice->retrieve("{INVOICE_ID}");

The above command returns JSON structured like this:

{
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46225> JSON: {
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}
Invoiced\Invoice JSON: {
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}

This endpoint retrieves a specific invoice.

HTTP Request

GET /invoices/:id

Query Parameters

Parameter Type Description
expand string Properties to expand

Update an invoice

curl "https://api.invoiced.com/invoices/:id" \
  -u {API_KEY}: \
  -X PATCH \
  -d sent=1 \
  -d chase=1
invoice.name = "July Paper Delivery"
invoice.notes = "The order was delivered on Jul 20, 2015"
invoice.sent = true
invoice.save
<?php

$invoice->name = "July Paper Delivery";
$invoice->notes = "The order was delivered on Jul 20, 2015";
$invoice->sent = true;
$invoice->save();

The above command returns JSON structured like this:

{
  "id": 46225,
  "customer": 15444,
  "name": "July Paper Delivery",
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": "The order was delivered on Jul 20, 2015",
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46225> JSON: {
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}
Invoiced\Invoice JSON: {
  "id": 46225,
  "customer": 15444,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "manual",
  "attempt_count": 0,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "items": [
    {
      "id": 7,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discounts": [],
      "taxes": []
    },
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "service",
      "name": "Delivery",
      "description": "",
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "created_at": 1415229884
}

Use this endpoint to update an invoice.

HTTP Request

PATCH /invoices/:id

Attributes

Parameter Type Description
name string Invoice name for internal use, defaults to “Invoice”
number string The reference number assigned to the invoice, defaults to next # in auto-numbering sequence
currency string 3-digit ISO 4217 currency code - defaults to account currency
payment_terms string Payment terms for the invoice, i.e. “NET 30” - inherited from customer by default
date timestamp Invoice date - defaults to current timestamp
due_date timestamp Due date - computed from payment_terms when not supplied
draft boolean When false, the invoice is considered outstanding, or when true, the invoice is a draft
sent boolean Marks an invoice as sent
closed boolean Marks an invoice as closed
chase boolean Enables chasing for this invoice
theme integer Theme ID for rendering with custom themes
items array Collection of Line Item objects
terms string Terms and conditions displayed on invoice
notes string Additional notes displayed on invoice
discounts array Collection of Discount objects
taxes array Collection of Tax objects

Send an invoice

curl "https://api.invoiced.com/invoices/:id/emails" \
  -u {API_KEY}: \
  -X POST
emails = invoice.send
<?php

$emails = $invoice->send();

The above command returns JSON structured like this:

[
  {
    "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
    "state": "sent",
    "reject_reason": null,
    "email": "client@example.com",
    "template": "new_invoice_email",
    "subject": "New Invoice from Dunder Mifflin, Inc.: INV-0016",
    "message": "Dear Client, a new invoice for $51.15 has been created on your account. [View and Pay Invoice button] Thank you!",
    "opens": 0,
    "opens_detail": [],
    "clicks": 0,
    "clicks_detail": [],
    "created_at": 1436890047
  },
  { ... },
  { ... }
]
[
  #<Invoiced::Email:0x3fdbf95e4d08 id="f45382c6fbc44d44aa7f9a55eb2ce731"> JSON: {
    "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
    "state": "sent",
    "reject_reason": null,
    "email": "client@example.com",
    "template": "new_invoice_email",
    "subject": "New Invoice from Dunder Mifflin, Inc.: INV-0016",
    "message": "Dear Client, a new invoice for $51.15 has been created on your account. [View and Pay Invoice button] Thank you!",
    "opens": 0,
    "opens_detail": [],
    "clicks": 0,
    "clicks_detail": [],
    "created_at": 1436890047
  },
  #<Invoiced::Email:0x3fdasdf95e09 id="a0s36fbc44d44aa7f9a55easdfi8ce731"> JSON: { ... },
  #<Invoiced::Email:0x3fdbffge4d10 id="s90f2c6fbc44sdfj8aa7f9a55eb2ce731"> JSON: { ... }
]
[
  Invoiced\Email JSON: {
    "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
    "state": "sent",
    "reject_reason": null,
    "email": "client@example.com",
    "template": "new_invoice_email",
    "subject": "New Invoice from Dunder Mifflin, Inc.: INV-0016",
    "message": "Dear Client, a new invoice for $51.15 has been created on your account. [View and Pay Invoice button] Thank you!",
    "opens": 0,
    "opens_detail": [],
    "clicks": 0,
    "clicks_detail": [],
    "created_at": 1436890047
  },
  Invoiced\Email JSON: { ... },
  Invoiced\Email JSON: { ... }
]

This endpoint sends an invoice to your customer.

HTTP Request

POST /invoices/:id/emails

Request Parameters

Parameter Type Description
to array Optional array of recipients like:
[{"name": "Client", "email": "client@example.com"}]
bcc string Optional comma-separated list of email addresses to be blind carbon copied
subject string Optional subject
message string Optional message body, otherwise the appropriate invoice template is used

Pay an invoice

curl "https://api.invoiced.com/invoices/:id/pay" \
  -u {API_KEY}: \
  -X POST
invoice.pay
<?php

$invoice->pay();

The above command returns JSON structured like this:

{
  "id": 46226,
  "customer": 15446,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": true,
  "status": "paid",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "auto",
  "attempt_count": 1,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0017",
  "date": 1416290402,
  "due_date": null,
  "payment_terms": "Auto-Charged",
  "items": [
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 5,
      "unit_cost": 45,
      "amount": 225,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 225,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 228.85,
  "balance": 228.85,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ/pdf",
  "created_at": 1415229885
}
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46226> JSON: {
  "id": 46226,
  "customer": 15446,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": true,
  "status": "paid",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "auto",
  "attempt_count": 1,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0017",
  "date": 1416290402,
  "due_date": null,
  "payment_terms": "Auto-Charged",
  "items": [
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 5,
      "unit_cost": 45,
      "amount": 225,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 225,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 228.85,
  "balance": 228.85,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ/pdf",
  "created_at": 1415229885
}
Invoiced\Invoice JSON: {
  "id": 46226,
  "customer": 15446,
  "name": null,
  "currency": "usd",
  "draft": false,
  "sent": false,
  "closed": false,
  "paid": true,
  "status": "paid",
  "chase": false,
  "next_chase_on": null,
  "collection_mode": "auto",
  "attempt_count": 1,
  "next_payment_attempt": null,
  "theme": null,
  "subscription": null,
  "number": "INV-0017",
  "date": 1416290402,
  "due_date": null,
  "payment_terms": "Auto-Charged",
  "items": [
    {
      "id": 8,
      "stored_item": null,
      "plan": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 5,
      "unit_cost": 45,
      "amount": 225,
      "discounts": [],
      "taxes": []
    }
  ],
  "terms": null,
  "notes": null,
  "subtotal": 225,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "amount": 3.85,
      "rate": null
    }
  ],
  "total": 228.85,
  "balance": 228.85,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ/pdf",
  "created_at": 1415229885
}

When an invoice is automatically collected we will perform the charge automatically. If a payment attempts fails then another attempt will be scheduled according to your retry settings. Or, you can trigger a charge attempt manually using this endpoint.

HTTP Request

POST /invoices/:id/pay

Delete an invoice

curl "https://api.invoiced.com/invoices/:id" \
  -u {API_KEY}: \
  -X DELETE
invoice.delete
<?php

$invoice->delete();

The above command returns 204 No Content

This endpoint deletes a specific invoice.

HTTP Request

DELETE /invoices/:id

List all invoices

curl "https://api.invoiced.com/invoices" \
  -u {API_KEY}:
invoices, metadata = invoiced.Invoice.list(:per_page => 3)
<?php

list($invoices, $metadata) = $invoiced->Invoice->list(['per_page' => 3]);

The above command returns JSON structured like this:

[
  {
    "id": 46225,
    "customer": 15444,
    "name": null,
    "currency": "usd",
    "draft": false,
    "sent": false,
    "closed": false,
    "paid": false,
    "status": "not_sent",
    "chase": false,
    "next_chase_on": null,
    "collection_mode": "manual",
    "attempt_count": 0,
    "next_payment_attempt": null,
    "theme": null,
    "subscription": null,
    "number": "INV-0016",
    "date": 1416290400,
    "due_date": 1417500000,
    "payment_terms": "NET 14",
    "items": [
      {
        "id": 7,
        "stored_item": null,
        "plan": null,
        "type": "product",
        "name": "Copy Paper, Case",
        "description": null,
        "quantity": 1,
        "unit_cost": 45,
        "amount": 45,
        "discounts": [],
        "taxes": []
      },
      {
        "id": 8,
        "stored_item": null,
        "plan": null,
        "type": "service",
        "name": "Delivery",
        "description": "",
        "quantity": 1,
        "unit_cost": 10,
        "amount": 10,
        "discounts": [],
        "taxes": []
      }
    ],
    "terms": null,
    "notes": null,
    "subtotal": 55,
    "discounts": [],
    "taxes": [
      {
        "id": 20554,
        "amount": 3.85,
        "rate": null
      }
    ],
    "total": 51.15,
    "balance": 51.15,
    "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
    "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415229884
  },
  { ... },
  { ... }
]
[
  #<Invoiced::Invoice:0x3fdbf95e4d08 id=46225> JSON: {
    "id": 46225,
    "customer": 15444,
    "name": null,
    "currency": "usd",
    "draft": false,
    "sent": false,
    "closed": false,
    "paid": false,
    "status": "not_sent",
    "chase": false,
    "next_chase_on": null,
    "collection_mode": "manual",
    "attempt_count": 0,
    "next_payment_attempt": null,
    "theme": null,
    "subscription": null,
    "number": "INV-0016",
    "date": 1416290400,
    "due_date": 1417500000,
    "payment_terms": "NET 14",
    "items": [
      {
        "id": 7,
        "stored_item": null,
        "plan": null,
        "type": "product",
        "name": "Copy Paper, Case",
        "description": null,
        "quantity": 1,
        "unit_cost": 45,
        "amount": 45,
        "discounts": [],
        "taxes": []
      },
      {
        "id": 8,
        "stored_item": null,
        "plan": null,
        "type": "service",
        "name": "Delivery",
        "description": "",
        "quantity": 1,
        "unit_cost": 10,
        "amount": 10,
        "discounts": [],
        "taxes": []
      }
    ],
    "terms": null,
    "notes": null,
    "subtotal": 55,
    "discounts": [],
    "taxes": [
      {
        "id": 20554,
        "amount": 3.85,
        "rate": null
      }
    ],
    "total": 51.15,
    "balance": 51.15,
    "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
    "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415229884
  },
  #<Invoiced::Invoice:0x3fdbf95e4d09 id=15445> JSON: { ... },
  #<Invoiced::Invoice:0x3fdbf95e4d10 id=15446> JSON: { ... }
]
[
  Invoiced\Invoice JSON: {
    "id": 46225,
    "customer": 15444,
    "name": null,
    "currency": "usd",
    "draft": false,
    "sent": false,
    "closed": false,
    "paid": false,
    "status": "not_sent",
    "chase": false,
    "next_chase_on": null,
    "collection_mode": "manual",
    "attempt_count": 0,
    "next_payment_attempt": null,
    "theme": null,
    "subscription": null,
    "number": "INV-0016",
    "date": 1416290400,
    "due_date": 1417500000,
    "payment_terms": "NET 14",
    "items": [
      {
        "id": 7,
        "stored_item": null,
        "plan": null,
        "type": "product",
        "name": "Copy Paper, Case",
        "description": null,
        "quantity": 1,
        "unit_cost": 45,
        "amount": 45,
        "discounts": [],
        "taxes": []
      },
      {
        "id": 8,
        "stored_item": null,
        "plan": null,
        "type": "service",
        "name": "Delivery",
        "description": "",
        "quantity": 1,
        "unit_cost": 10,
        "amount": 10,
        "discounts": [],
        "taxes": []
      }
    ],
    "terms": null,
    "notes": null,
    "subtotal": 55,
    "discounts": [],
    "taxes": [
      {
        "id": 20554,
        "amount": 3.85,
        "rate": null
      }
    ],
    "total": 51.15,
    "balance": 51.15,
    "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
    "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415229884
  },
  Invoiced\Invoice JSON: { ... },
  Invoiced\Invoice JSON: { ... }
]

This endpoint retrieves all invoices.

HTTP Request

GET /invoices

Query Parameters

Parameter Description
sort string Column to sort by, i.e. name asc
filter object Filter object
start_date timestamp Restricts the results to invoices on or after the given timestamp
end_date timestamp Restricts the results to invoices on or before the given timestamp

Transactions

Transactions can represent a charge, payment, refund, or adjustment.

We record charge and refund transactions for you that happen through Invoiced. The payment transaction type is designated for recording offline payments like checks. Finally, an adjustment transaction represents any additional credit or debits to a customer’s balance.

Most transactions will be associated with an invoice, however, not all. For example, if you wanted to credit your customer for $20 you would create an adjustment transaction for -$20 using the customer ID only instead of the invoice ID.

We currently support the following payment methods on transactions:

Transaction Object

Attributes

{
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}
#<Invoiced::Transaction:0x3fdbf95e4d08 id=20939> JSON: {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}
Invoiced\Transaction JSON: {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}
Parameter Type Description
id integer The transaction’s unique ID
customer integer Associated Customer
invoice integer Associated Invoice, if any
theme integer Theme ID for rendering with custom themes
date timestamp Transaction date
type string Transaction type, charge, payment, refund, or adjustment
method string Payment instrument used to facilitate transaction
status string Transaction status, one of succeeded, pending, or failed
gateway string Payment gateway that processed the transaction, if any
gateway_id string Transaction ID from the payment gateway
currency string 3-digit ISO 4217 currency code
amount number Transaction amount
fee number Processing fees
notes string Internal notes
sent boolean Indicates if the transaction receipt has been sent’
parent_transaction integer ID of the original transaction for refunds
pdf_url string URL to download the invoice as a PDF
created_at timestamp Timestamp when created

Create a transaction

curl "https://api.invoiced.com/transaction" \
  -u {API_KEY}: \
  -d invoice=44648 \
  -d method="check" \
  -d gateway_id="1450" \
  -d amount=800
invoiced.Transaction.create(
  :invoice => 44648,
  :method => "check",
  :gateway_id => "1450",
  :amount => 800
)
<?php

$invoiced->Transaction->create([
  'invoice' => 44648,
  'method' => "check",
  'gateway_id' => "1450",
  'amount' => 800
]);

The above command returns JSON structured like this:

{
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": "1450",
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}
#<Invoiced::Transaction:0x3fdbf95e4d08 id=30939> JSON: {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}
Invoiced\Transaction JSON: {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}

Create a new transaction with this endpoint.

HTTP Request

POST /transactions

Attributes

Parameter Type Description
customer integer Customer ID, required if invoice ID is not supplied
invoice integer Invoice ID, if any
type string Transaction type, charge, payment, refund, or adjustment - required
date timestamp Transaction date, defaults to current timestamp
theme integer Theme ID for rendering with custom themes
method string Payment instrument used to facilitate transaction, defaults to other
status string Transaction status, one of succeeded, pending, or failed, defaults to succeeded
gateway string Payment gateway that processed the transaction, if any
gateway_id string Transaction ID from the payment gateway, or check # if method is check
currency string 3-digit ISO 4217 currency code
amount number Transaction amount
fee number Processing fees
notes string Internal notes

Retrieve a transaction

curl "https://api.invoiced.com/transactions/:id" \
  -u {API_KEY}:
transaction = invoiced.Transaction.retrieve("{TRANSACTION_ID}")
<?php

$transaction = $invoiced->Transaction->retrieve("{TRANSACTION_ID}");

The above command returns JSON structured like this:

{
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}
#<Invoiced::Transaction:0x3fdbf95e4d08 id=20939> JSON: {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}
Invoiced\Transaction JSON: {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}

This endpoint retrieves a specific transaction.

HTTP Request

GET /transactions/:id

Update a transaction

curl "https://api.invoiced.com/transactions/:id" \
  -u {API_KEY}: \
  -d notes="Check was received by Jan" \
  -X PATCH
transaction.notes = "Check was received by Jan"
transaction.save
<?php

$transaction->notes = "Check was received by Jan";
$transaction->save();

The above command returns JSON structured like this:

{
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": "Check was received by Jan",
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}
#<Invoiced::Transaction:0x3fdbf95e4d08 id=20939> JSON: {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": "Check was received by Jan",
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}
Invoiced\Transaction JSON: {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": "Check was received by Jan",
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
}

Use this endpoint to update a transaction.

HTTP Request

PATCH /transactions/:id

Request Parameters

Parameter Type Description
date timestamp Transaction date, defaults to current timestamp
theme integer Theme ID for rendering with custom themes
method string Payment instrument used to facilitate transaction, defaults to other
status string Transaction status, one of succeeded, pending, or failed, defaults to succeeded
gateway string Payment gateway that processed the transaction, if any
gateway_id string Transaction ID from the payment gateway, or check # if method is check
currency string 3-digit ISO 4217 currency code
amount number Transaction amount
fee number Processing fees
notes string Internal notes

Send a receipt

curl "https://api.invoiced.com/transactions/:id/emails" \
  -u {API_KEY}: \
  -X POST
emails = transaction.send
<?php

$emails = $transaction->send();

The above command returns JSON structured like this:

[
  {
    "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
    "state": "sent",
    "reject_reason": null,
    "email": "client@example.com",
    "template": "payment_receipt_email",
    "subject": "Receipt for your recent payment to Dunder Mifflin, Inc.",
    "message": "Dear Client, we have attached a receipt for your most recent payment. Thank you!",
    "opens": 0,
    "opens_detail": [],
    "clicks": 0,
    "clicks_detail": [],
    "created_at": 1436890047
  },
  { ... },
  { ... }
]
[
  #<Invoiced::Email:0x3fdbf95e4d08 id="f45382c6fbc44d44aa7f9a55eb2ce731"> JSON: {
    "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
    "state": "sent",
    "reject_reason": null,
    "email": "client@example.com",
    "template": "payment_receipt_email",
    "subject": "Receipt for your recent payment to Dunder Mifflin, Inc.",
    "message": "Dear Client, we have attached a receipt for your most recent payment. Thank you!",
    "opens": 0,
    "opens_detail": [],
    "clicks": 0,
    "clicks_detail": [],
    "created_at": 1436890047
  },
  #<Invoiced::Email:0x3fdasdf95e09 id="a0s36fbc44d44aa7f9a55easdfi8ce731"> JSON: { ... },
  #<Invoiced::Email:0x3fdbffge4d10 id="s90f2c6fbc44sdfj8aa7f9a55eb2ce731"> JSON: { ... }
]
[
  Invoiced\Email JSON: {
    "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
    "state": "sent",
    "reject_reason": null,
    "email": "client@example.com",
    "template": "payment_receipt_email",
    "subject": "Receipt for your recent payment to Dunder Mifflin, Inc.",
    "message": "Dear Client, we have attached a receipt for your most recent payment. Thank you!",
    "opens": 0,
    "opens_detail": [],
    "clicks": 0,
    "clicks_detail": [],
    "created_at": 1436890047
  },
  Invoiced\Email JSON: { ... },
  Invoiced\Email JSON: { ... }
]

This endpoint sends a PDF receipt to the customer.

HTTP Request

POST /transactions/:id/emails

Request Parameters

Parameter Type Description
to array Optional array of recipients like:
[{"name": "Client", "email": "client@example.com"}]
bcc string Optional comma-separated list of email addresses to be blind carbon copied
subject string Optional subject
message string Optional message body, otherwise the Payment Receipt Email template is used

Refund a transaction

curl "https://api.invoiced.com/transactions/:id/refunds" \
  -u {API_KEY}: \
  -X POST
transaction = transaction.refund(:amount => 400)
<?php

$refund = $transaction->refund(['amount' => 400]);

The above command returns JSON structured like this:

{
    "id": 20952,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "refund",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 400,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": 20939,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/20939pdf",
    "created_at": 1415228628
}
#<Invoiced::Transaction:0x3fdbf95e4d08 id=20952> JSON: {
    "id": 20952,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "refund",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 400,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": 20939,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/20939pdf",
    "created_at": 1415228628
}
Invoiced\Transaction JSON: {
    "id": 20952,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "refund",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 400,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": 20939,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/20939pdf",
    "created_at": 1415228628
}

You can issue a refund for charge and payment transactions. When a refund is issued for a charge transaction we will attempt to initiate the refund over the payment gateway it happened on.

Of course, when refunding payment transactions you would have to return the money to your customer. This endpoint simply provides a means to track any refunds that you issue for offline payments.

Partial refunds are allowed, however, the total amount refunded cannot exceed the original transaction amount.

HTTP Request

POST /transactions/:id/refunds

Request Parameters

Parameter Type Description
amount number Amount to refund - required

Delete a transaction

curl "https://api.invoiced.com/transactions/:id" \
  -u {API_KEY}: \
  -X DELETE
transaction.delete
<?php

$transaction->delete();

The above command returns 204 No Content

This endpoint deletes a specific transaction.

HTTP Request

DELETE /transactions/:id

List all transactions

curl "https://api.invoiced.com/transactions" \
  -u {API_KEY}:
transactions, metadata = invoiced.Transaction.list(:per_page => 3)
<?php

list($transactions, $metadata) = $invoiced->Transaction->list(['per_page' => 3]);

The above command returns JSON structured like this:

[
  {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
  },
  { ... },
  { ... }
]
[
  #<Invoiced::Transaction:0x3fdbf95e4d08 id=20939> JSON: {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
  },
  #<Invoiced::Transaction:0x3fdbf95e4d09 id=20940> JSON: { ... },
  #<Invoiced::Transaction:0x3fdbf95e4d10 id=20941> JSON: { ... }
]
[
  Invoiced\Transaction JSON: {
    "id": 20939,
    "customer": 15460,
    "invoice": 44648,
    "theme": null,
    "date": 1410843600,
    "type": "payment",
    "method": "check",
    "status": "succeeded",
    "gateway": null,
    "gateway_id": null,
    "currency": "usd",
    "amount": 800,
    "fee": 0,
    "notes": null,
    "sent": false,
    "failure_reason": null,
    "parent_transaction": null,
    "pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "created_at": 1415228628
  },
  Invoiced\Transaction JSON: { ... },
  Invoiced\Transaction JSON: { ... }
]

This endpoint retrieves all transactions.

HTTP Request

GET /transactions

Query Parameters

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