MoneyBird API

Introduction | Contacts | Estimates | Incoming invoices | Invoice profiles | Invoices | Products | Recurring invoices | Tax rates

Invoices API

This page contains all the information you need for managing invoices. Below you will find all the available attributes for the XML API and some examples to get you started.

Table 1. Invoice commands
Description Method & URL
Get all invoices GET/api/v1.0/invoices.xml
Get all invoices filtered GET/api/v1.0/invoices/filter/:filter.xml
Get all invoices filtered advanced by parameters POST/api/v1.0/invoices/filter/advanced.xml
Get invoice GET/api/v1.0/invoices/:id.xml
Get invoice by invoice_id GET/api/v1.0/invoices/invoice_id/:invoice_id.xml
Create new invoice POST/api/v1.0/invoices.xml
Update invoice PUT/api/v1.0/invoices/:id.xml
Send invoice PUT/api/v1.0/invoices/:id/send_invoice.xml
Send invoice reminder PUT/api/v1.0/invoices/:id/send_reminder.xml
Register payment POST/api/v1.0/invoices/:id/payments.xml
Delete invoice DELETE/api/v1.0/invoices/:id.xml
Get list of invoices for syncing GET/api/v1.0/invoices/sync_list_ids.xml
Get specified invoices for syncing POST/api/v1.0/invoices/sync_fetch_ids.xml
Table 2. Invoice attributes
Attribute Type Required Note
address1 String No Address line 1 of contact
address2 String No Address line 2 of contact
attention String No Attention of contact
city String No City of contact
company-name String Yes At least a contact-id for existing contact or company-name, firstname or lastname required for new contact
concept-id Integer No Read-only
contact-id Integer Yes At least a contact-id for existing contact or company-name, firstname or lastname required for new contact
contact-name String No Read-only, firstname + lastname
country String No Country of contact
created-at Datetime No Read-only, for example: 2011-02-15T13:13:50+01:00
currency String No Default: the currency of the document profile. For example: EUR, GBP or USD
customer-id String No Customer id of contact
days-open Integer No Read-only, date today - invoice date in days
description String No Default: the description of the document profile. For example: Please pay invoice by bank-transfer. (footer of invoice)
discount Decimal No Default: 0. For example: 17.5 is 17.5% discount
due-date-interval Integer No Default: the due-date-interval of the document profile. For example: 14 (number of days after which the invoice will due)
email String No Read-only, the email address the invoice was sent to
exchange-rate Decimal No Read-only, exchange rate is 1 if invoice currency is the same as company base currency
firstname String Yes At least a contact-id for existing contact or company-name, firstname or lastname required for new contact
id Integer No Read-only, the unique id of the invoice
invoice-date Date No For example: 2011-03-27, if omited the invoice-date will be assigned when you send the invoice
invoice-email String No Read-only, text of email from document profile
invoice-email-reminder String No Read-only, text of email reminder from document profile
invoice-hash String No Read-only, unique hash for the invoice
invoice-id String No For example: 2011-0009, if omited the invoice-id will be assigned when you send invoice
invoice-profile-id Integer No Default: the id of the default document profile
invoice-profile-version-id Integer No Don't set this attribute, the server will pick the right version id
language String No Default: the language of the document profile. For example: nl or en
lastname String Yes At least a contact-id for existing contact or company-name, firstname or lastname required for new contact
name String No Read-only, company-name or firstname + lastname
original-estimate-id Integer No Read-only
original-invoice-id Integer No Read-only
pay-url String No Read-only, if any payment gateway is activated for this contact, this is the url where contact can pay
po-number String No Reference on invoice
prices-are-incl-tax Boolean No Default: false
recurring-template-id Integer No Read-only
revision Integer No Read-only, incremental integer, increases if invoice is updated
send-method String No Read-only
show-customer-id Boolean No Default: the show-customer-id of the document profile. For example: true or false (show or don't show customer id of contact on invoice)
show-tax Boolean No Default: the show-tax of the document profile. For example: true or false (enable or disable TAX on invoice)
show-tax-number Boolean No Default: the show-tax-number of the document profile. For example: true or false (show or don't show TAX number of contact on invoice)
state String No Read-only, can be: draft, open, late or paid
tax-number String No Default: the TAX number of the contact
total-paid Decimal No Read-only
total-price-excl-tax Decimal No Read-only
total-price-excl-tax-base Decimal No Read-only, in default currency of company
total-price-incl-tax Decimal No Read-only
total-price-incl-tax-base Decimal No Read-only, in default currency of company
total-tax Decimal No Read-only
total-unpaid Decimal No Read-only
updated-at Datetime No Read-only, for example: 2011-02-15T13:13:50+01:00
url String No Read-only, the url for the invoice online
zipcode String No Default: the zipcode of the contact
Table 3. Invoice detail attributes
Attribute Type Required Note
amount String No For example: 1 x or 2 hours
created-at Datetime No Read-only, for example: 2011-02-15T13:13:50+01:00
description String Yes Description of invoice detail, for example: Table ABC format 140x90
id Integer No Read-only, unique id of invoice detail
invoice-id Integer No Read-only, unique id of invoice
ledger-account-id Integer No For MoneyBird Plus users, you can provide a ledger-account-id
price Decimal No Default: 0.0. For example: 19.95
row-order Integer No Give a row a fixed position in table
tax-rate-id Integer Yes
total-price-excl-tax Decimal No Read-only
total-price-incl-tax Decimal No Read-only
updated-at Datetime No Read-only, for example: 2011-02-15T13:13:50+01:00
Table 4. Invoice history attributes
Attribute Type Required Note
action String No If empty, description attribute contains a note. If not empty, values can be: invoice_created, invoice_paid, invoice_paid_mail_sent, invoice_reminder_sent, invoice_reminder_sent_email, invoice_reminder_sent_hand, invoice_reminder_sent_post, invoice_sent, invoice_sent_email, invoice_sent_hand, invoice_sent_post
created-at Datetime No Read-only, for example: 2011-02-15T13:13:50+01:00
description String No A note if action attribute is empty or some comment to one of the other actions
id Integer No Read-only, the unique id of the invoice history
invoice-id Integer No Read-only, the unique id of the invoice
updated-at Datetime No Read-only, for example: 2011-02-15T13:13:50+01:00
user-id Integer No Read-only, the user who did the action
Table 5. Invoice payment attributes
Attribute Type Required Note
created-at Datetime No Read-only, for example: 2011-02-15T13:13:50+01:00
credit-invoice-id Integer No Read-only, if payment is credit-invoice, reference to credit-invoice
id Integer No Read-only, the unique id of the invoice payment
invoice-id Integer No Read-only, the unique id of the invoice
payment-date Date No For example: 2011-02-27
payment-method String No Values can be: bank_transfer, creditcard, direct_debit, ideal, paypal, pin
price Decimal No For example: 119.0
updated-at Datetime No Read-only, for example: 2011-02-15T13:13:50+01:00
Table 6. Send invoice attributes
Attribute Type Required Note
email String Yes Email address of receiver
invoice-email String Yes Content of the email you send to the receiver
send-method String Yes Values can be: email, hand or post

Get filtered invoices

GET /api/v1.0/invoices/filter/all.xml
GET /api/v1.0/invoices/filter/draft.xml
GET /api/v1.0/invoices/filter/last_month.xml
GET /api/v1.0/invoices/filter/last_quarter.xml
GET /api/v1.0/invoices/filter/open.xml
GET /api/v1.0/invoices/filter/sent.xml
GET /api/v1.0/invoices/filter/this_month.xml
GET /api/v1.0/invoices/filter/this_quarter.xml
GET /api/v1.0/invoices/filter/this_year.xml

Create invoice

POST /api/v1.0/invoices.xml
Response code: 201

Post the following data:


<invoice>
  <contact-id>123</contact-id>
  <details-attributes type="array">
    <detail>
      <amount>1 x</amount>
      <description>Table size: 140x90</description>
      <price>100</price>
      <tax-rate-id>1</tax-rate-id>
    </detail>
  </details-attributes>
</invoice>

Update invoice details 1 (create new detail)

PUT /api/v1.0/invoices/123.xml
Response code: 200

Put the following data:


<invoice>
  <details-attributes type="array">
    <detail>
      <amount>2 x</amount>
      <description>New invoice detail</description>
      <price>200</price>
      <tax-rate-id>1</tax-rate-id>
    </detail>
  </details-attributes>
</invoice>

Update invoice details 2 (update detail)

PUT /api/v1.0/invoices/123.xml
Response code: 200

Put the following data:


<invoice>
  <details-attributes type="array">
    <detail>
      <amount>2 x</amount>
      <description>Table size: 140x90</description>
      <id>10</id>
      <price>200</price>
      <tax-rate-id>1</tax-rate-id>
    </detail>
  </details-attributes>
</invoice>

Update invoice details 3 (delete detail)

PUT /api/v1.0/invoices/123.xml
Response code: 200

Put the following data:


<invoice>
  <details-attributes type="array">
    <detail>
      <_destroy>true</_destroy>
      <id>10</id>
    </detail>
  </details-attributes>
</invoice>

Send invoice

PUT /api/v1.0/invoices/123/send_invoice.xml
Or:
PUT /api/v1.0/invoices/123/send_reminder.xml
Response code: 200

Put the following data:


<invoice>
  <email>my@email-address.com</email>
  <invoice-email>Hereby the invoice</invoice-email>
  <send-method>email</send-method>
</invoice>

Register payment for invoice

POST /api/v1.0/invoices/123/payments.xml
Response code: 201

Post the following data:


<payment>
  <payment-date>2011-03-19</payment-date>
  <payment-method>creditcard</payment-method>
  <price>119.80</price>
  <send-email>false</send-email>
</payment>

Delete an existing invoice

DELETE /api/v1.0/invoices/123.xml
Response code: 200

Get list of invoices for syncing

GET /api/v1.0/invoices/sync_list_ids.xml
Response code: 200

Response:


<?xml version="1.0" encoding="UTF-8"?>
<invoices>
  <invoice>
    <id>1234</id>
    <revision>123456789</revision>
  </invoice>
  ...
</invoices>

Note: if your local value of revision is not equal to the remote value of revision, use sync_fetch_ids to fetch them.

Get specified invoices for syncing

POST /api/v1.0/invoices/sync_fetch_ids.xml
Response code: 200

Post the following data:


<?xml version="1.0" encoding="UTF-8"?>
<invoices>
  <ids>
    <id>1</id>
    <id>5</id>
  </ids>
</invoices>

Response:


<?xml version="1.0" encoding="UTF-8"?>
<invoices>
  <invoice>
    ...
  </invoice>
  ...
</invoices>

Note: returns max 100 invoices, even if number of ids in request is greater than 100

Vragen? Bekijk de help of neem contact op!
support@moneybird.nl

Laatste nieuws van ons blog

Twitter Facebook LinkedIn RSS


© 2013 BlueTools B.V.. Alle rechten voorbehouden. BlueTools B.V. is ingeschreven bij de KVK te Enschede nr. 8155914.