Invoices API

Clientary provides programmatic access to invoices and invoice items.

Get All Invoices

GET /api/v2/invoices

{
  "page_count": 3
  "page_size": 30
  "total_count": 61
  "invoices": [
    {
      "tax": 5
      "number": "184"
      "total_cost": 129.15
      "balance": 129.15
      "subtotal": 123
      "title": ""
      "tax_label": "Sales Tax"
      "compound_tax": true
      "id": 110
      "date": "2011/07/26"
      "client_id": 4
      "note": ""
      "due_date": "2011/08/25"
      "invoice_items": [
        {
          "price": 123
          "title": "Invoice Item"
          "quantity": 1
          "taxable": true
          "id": 184
        },
        ...
      ]
      "tax2_label": "Secondary Tax"
      "summary": null
      "recurring_schedules": [
        { "id"=>1 },
        ...
      ]
      "total_payments": 0
      "tax2": 0
      "status": 0
      "po": ""
      "currency_code": "EUR"
      "payments": [
        {
          "received_on": "2011/07/29"
          "amount": 10
          "id": 2053932801
          "note": "Paid by check"
        }
      ]
      "tax3_label": "Tertiary Tax"
      "tax3": 0
    },
    ...
  ]
}

Invoice Status Values:

0: Draft
1: Sent
2: Viewed
3: Cancelled
4: Paid

Invoice Item Type Values:

0: Section Header
3: Regular Invoice Line Item

GET /api/v2/invoices?page=2

On a bulk GET Clientary will return 30 results at once. To paginate through more results, you can use the page parameter.

GET /api/v2/invoices?updated_since=2011-01-01

You can also filter by update time for invoices, just to get the lastest changes.

GET /api/v2/clients/:client_id/invoices

You can also fetch invoices under a specific client.

GET /api/v2/projects/:project_id/invoices

You can also fetch invoices associated with a specific project.

GET /api/v2/recurring/:id/invoices

You can also fetch invoices associated with a specific recurring schedule.

Get An Invoice

GET /api/v2/invoices/:id

{
  "tax": 5
  "number": "184"
  "total_cost": 129.15
  "balance": 129.15
  "subtotal": 123
  "title": ""
  "tax_label": "Sales Tax"
  "compound_tax": true
  "id": 110
  "date": "2011/07/26"
  "client_id": 4
  "note": ""
  "due_date": "2011/08/25"
  "invoice_items": [
    {
      "price": 123
      "title": "Invoice Item"
      "quantity": 1
      "taxable": true
      "id": 184
    },
    ...
  ]
  "tax2_label": "Secondary Tax"
  "summary": null
  "recurring_schedules": [
    { "id"=>1 },
    ...
  ]
  "total_payments": 0
  "tax2": 0
  "status": 0
  "po": ""
  "currency_code": "EUR"
  "payments": [
    {
      "received_on": "2011/07/29"
      "updated_at": "2011/06/29 23:01:08 -0700"
      "invoice_id": 110
      "amount": 10
      "id": 2053932801
      "note": "Paid by check"
    }
  ]
  "tax3_label": "Tertiary Tax"
  "tax3": 0
}

Create A New Invoice

POST /api/v2/invoices

{
  "invoice": {
    "number": 185,
    "date": "2011-07-29",
    "due_date": "2011-08-28",
    "currency_code": "USD",
    "invoice_items_attributes": [
      {
        "title": "foo",
        "quantity": 1,
        "price": 100
      },
      {
        "title": "bar",
        "quantity": 2,
        "price": 200
      }
    ]
  }
}

Required Fields: date, currency_code, due_date (HTTP 422 on failure)
Optional Fields: number will be autoincremented from previous invoice numbers if not provided
Conditional Fields: invoice_item_attributes.title, invoice_item_attributes.quantity, invoice_item_attributes.price must be provided if any items are added (HTTP 422 on failure)
Unique Fields: number (HTTP 422 on failure)

POST /api/v2/clients/:client_id/invoices

You can also create invoices directly under a specific client. Alternatively, you can use the client_id attribute for specifying the client. Note that this is optional as invoices can be created without a client.

Update An Invoice

PUT /api/v2/invoice/:id

You may provide a partial list of fields to update

  {
    "invoice": {
      "number": 185,
      "date": "2011-07-29",
      "due_date": "2011-08-28",
      "currency_code": "USD",
      "invoice_items_attributes": [
        {
          "id": 501,
          "_destroy": true
        },
        {
          "id": 502
          "title": "bar",
          "quantity": 2,
          "price": 200
        },
        {
          "title": "bar",
          "quantity": 2,
          "price": 200
        }
      ]
    }
  }

In invoice_items_attributes, provide id to edit an existing invoice_item or omit id to create new invoice items. Provide _destroy attribute along with id to delete the invoice item.

Unique Fields: number (HTTP 422 on failure)

Delete An Invoice

DELETE /api/v2/invoices/:id

Deleting an invoice will result in the deletion of all associated Invoice Items and Payments. Deletions are permanent and not reversible.

Send An Invoice

POST /api/v2/invoices/:id/messages

{
  "recipients": ["[email protected]", "[email protected]"],
  "subject": "Subject for invoice",
  "message": "Body message for invoice",
  "send_copy": 1,
  "attach_pdf": 1
}

Required Fields: recipients - an array of email addresses. (HTTP 422 on failure)
Encouraged Fields: subject, message are strongly encouraged, since this is what displays in the email, but it is not required.
Optional Fields: send_copy optionally allows the sending user (dependent on API Token used) to receive a copy of the email, attach_pdf allows an optional PDF to be attached to the invoice.