API Documentation - Version 1.0
Invoices
Introduction
With this API you will be able to manage your invoices. You can create, update and delete your invoices as well as retrieve a list of invoices.
List Invoices
Endpoint: GET api/1.0/invoices
Parameters
Parameter | Type | Status | Description |
---|---|---|---|
page | integer | optional | Parameter to paginate the result set. |
Example Request
curl -X GET -G "https://addrow.io/api/1.0/invoices" \
-H "Authorization: Bearer {token}"
Example Responses
Status 200
{
"data": [
{
"id": "dPQaqP",
"invoice_number": "201901",
"items": [
{
"description": "Example Item",
"quantity": 1,
"price": "159"
}
],
"status": "pending",
"sub_total": 159,
"tax_percentage": 9,
"vat_shifted": 0,
"total": "173.31",
"invoice_date": "2019-09-22T18:32:40.000000Z",
"payment_term": 14,
"remind_at": null,
"sent_at": null,
"due_date": "2019-10-06",
"created_at": "2019-09-22T18:32:40.000000Z",
"updated_at": "2019-09-22T18:32:40.000000Z",
"paid_at": null,
"user_id": 1,
"profile_id": "wzL7EG",
"customer_id": "DrdKzv",
"customer": {
"name": "Jan Jansen",
"company_name": "Jansen & Zn.",
"address": "Hoogakker 2F",
"zipcode": "6721 ZH",
"city": "Bennekom",
"country": "NL",
"phone": "+31612345678",
"email": "[email protected]",
"created_at": "2019-08-01 12:01:58",
"updated_at": "2019-08-02 22:33:28",
"country_label": "Nederland"
},
"reminders": [],
"pdf": "https:\/\/addrow.io\/downloads\/invoices\/..."
}
],
"links": {
"first": "https:\/\/addrow.io\/api\/1.0\/invoices?page=1",
"last": "https:\/\/addrow.io\/api\/1.0\/invoices?page=3",
"prev": null,
"next": "https:\/\/addrow.io\/api\/1.0\/invoices?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 3,
"path": "https:\/\/addrow.io\/api\/1.0\/invoices",
"per_page": 15,
"to": 15,
"total": 32
}
}
Status 401
{
"message": "Unauthenticated."
}
Create Invoice
Endpoint POST api/1.0/invoices
Parameters
Parameter | Type | Status | Description |
---|---|---|---|
payment_term | integer | optional | Days before payment is due. When empty, uses settings. |
customer_id | string | required | The ID of the customer receiving this invoice. |
profile_id | string | required | The ID of the company profile you are sending the invoice from. |
status | string | optional | Can be draft, pending or paid. |
note | string | optional | Note at the bottom of the invoice. When empty, the profile settings are used. |
vat_shifted | integer | optional | Mark the VAT as shifted (0 = false, 1 = true). |
tax_percentage | integer | optional | The tax percentage. |
items | array | required | The invoice items. Every row in the items array, must contain the following: an description (string), quantity (integer) and price (float). |
Example Request
curl -X POST "https://addrow.io/api/1.0/invoices" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"customer_id":"DrdKzv","profile_id":"wzL7EG","items": [
{
"description": "Yearly Webhosting",
"quantity": "1",
"price": "90"
}
]}'
Example Responses
Status 200
{
"data": {
"id": "dPQaqP",
"invoice_number": null,
"items": [
{
"description": "Yearly Webhosting",
"quantity": "1",
"price": "90"
}
],
"status": "draft",
"sub_total": 74.3801652892562,
"tax_percentage": "21",
"vat_shifted": 0,
"total": 90,
"invoice_date": "2020-03-26T23:52:21.000000Z",
"payment_term": "14",
"remind_at": null,
"sent_at": null,
"due_date": "2020-04-09T00:00:00.000000Z",
"created_at": "2020-03-26T23:52:21.000000Z",
"updated_at": "2020-03-26T23:52:21.000000Z",
"paid_at": null,
"user_id": 6,
"profile_id": "wzL7EG",
"customer_id": "DrdKzv",
"customer": {
"name": "Jan Jansen",
"company_name": "Jansen & Zn.",
"address": "Hoogakker 2F",
"zipcode": "6721 ZH",
"city": "Bennekom",
"country": "NL",
"phone": "+31612345678",
"email": "[email protected]",
"created_at": "2019-08-01 12:01:58",
"updated_at": "2019-08-02 22:33:28",
"country_label": "Nederland"
},
"note": "Thank you for working with us!",
"reminders": [],
"pdf": null
}
}
Status 401
{
"message": "Unauthenticated."
}
Update Invoice
Only invoices with the status set to draft
can be updated.
Endpoint PATCH api/1.0/invoices/{id}
Parameters
Parameter | Type | Status | Description |
---|---|---|---|
payment_term | integer | optional | Days before payment is due. When empty, uses settings. |
customer_id | string | required | The ID of the customer receiving this invoice. |
profile_id | string | required | The ID of the company profile you are sending the invoice from. |
status | string | optional | Can be draft, pending or paid. |
note | string | optional | Note at the bottom of the invoice. When empty, the profile settings are used. |
vat_shifted | integer | optional | Mark the VAT as shifted (0 = false, 1 = true). |
tax_percentage | integer | optional | The tax percentage. |
items | array | required | The invoice items. |
Every row in the items
array, must contain the following: an description (string), quantity (integer) and price (float).
Example Request
curl -X PATCH "https://addrow.io/api/1.0/{id}" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"note":"Thank you for working with us!","vat_shifted":0,"tax_percentage":21}'
Example Responses
Status 200
{
"data": {
"id": 1,
"invoice_number": "201901",
"items": [
{
"description": "Example Item",
"quantity": 1,
"price": "159"
}
],
"status": "pending",
"sub_total": 159,
"tax_percentage": 9,
"vat_shifted": 0,
"total": "173.31",
"invoice_date": "2019-09-22T18:32:40.000000Z",
"payment_term": 14,
"remind_at": null,
"sent_at": null,
"due_date": "2019-10-06",
"created_at": "2019-09-22T18:32:40.000000Z",
"updated_at": "2019-09-22T18:32:40.000000Z",
"paid_at": null,
"user_id": 1,
"profile_id": "wzL7EG",
"customer_id": "DrdKzv",
"customer": {
"name": "Jan Jansen",
"company_name": "Jansen & Zn.",
"address": "Hoogakker 2F",
"zipcode": "6721 ZH",
"city": "Bennekom",
"country": "NL",
"phone": "+31612345678",
"email": "[email protected]",
"created_at": "2019-08-01 12:01:58",
"updated_at": "2019-08-02 22:33:28",
"country_label": "Nederland"
},
"reminders": [],
"pdf": "https:\/\/addrow.io\/downloads\/invoices\/..."
}
}
Delete Invoice
You can delete an invoice when it is in the draft status.
Example Request
curl -X DELETE "https://addrow.io/api/1.0/invoices/{id}" \
-H "Authorization: Bearer {token}"
Example Responses
Response 200
{
"message": "Invoice has been deleted"
}
Actions
For invoices, there a couple of additional actions available.
Send
Send the invoice to the customer's email address. The invoice can only emailed once. Based on your settings, reminders will be send automatically.
Endpoint: POST api/1.0/invoices/{id}/actions/send
Example Request
curl -X POST "https://addrow.io/api/1.0/invoices/{id}/actions/send" \
-H "Authorization: Bearer {token}"
Mark as Paid
Marks the invoice as paid, setting the payment date on the current date. If you'd like more controll over this, you can instead use the Update Invoice option.
Endpoint: POST api/1.0/invoices/{id}/actions/mark-as-paid
Example Request
curl -X POST "https://addrow.io/api/1.0/invoices/{id}/actions/mark-as-paid" \
-H "Authorization: Bearer {token}"
Mark as Pending
Endpoint: POST api/1.0/invoices/{id}/actions/mark-as-pending
Example Request
curl -X POST "https://addrow.io/api/1.0/invoices/{1}/actions/mark-as-pending" \
-H "Authorization: Bearer {token}"