Invoices API

Ronin provides programmatic access to invoices and invoice items.

There is no separate API for individual invoice items but there is one for Payments.

Get All Invoices

GET /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
      "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"
        }
      ]
    },
    ...
  ]
}

GET /invoices?page=2

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

GET /invoices?updated_since=2011-01-01

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

GET /clients/:client_id/invoices

You can also fetch invoices under a specific client.

Get An Invoice

GET /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
  "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"
    }
  ]
}

Create A New Invoice

POST /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: number, date, currency_code, due_date (HTTP 422 on failure)
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)

Update An Invoice

PUT /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 /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 /invoices/:id/messages

{
  "recipients": "abc@example.com", "xyz@example.com",
  "subject": "Subject for invoice", 
  "message": "Body message for invoice", 
  "send_copy": 1,
  "attach_pdf": 1
}

Required Fields: recipients - a comment delimited list 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.

Payments

You can programmatically apply a payment to an invoice or remove an existing payment.

You can view payment information via the Invoice API. The Payment API is only for creation and deletion.

Post A New Invoice Payment

POST /invoices/:invoice_id/payments

{
  "payment": {
    "amount": 500,
    "note": "Paid by Check"
  }
}

Required Fields: amount (HTTP 422 on failure)

Post A New Invoice Payment and Auto-Charge Client Payment Profile

POST /invoices/:invoice_id/payments

{
  "payment": {
    "payment_profile_id": 123
  }
}

Required Fields: payment_profile_id (HTTP 422 on failure)
Note that if a payment_profile_id is used, amount and note are ignored. This implies that the entire outstanding amount of the invoice will be charged.

Delete A Payment

DELETE /invoices/:invoice_id/payments/:id

Deletion of payment requires presence of invoice_id.

Deletions are permanent and not reversible.