Invoices

The Invoice Object

NOTE: This is a sample invoice object with Taxes, Discounts and Shipping charges added to the invoice subtotal.

EXAMPLE OBJECT

{
  "invoice": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "total_due": "0.00",
    "paid_total": "0.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [{
      "id": 3,
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts": [{
      "id": 4,
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts": [{
      "id": 5,
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items": [{
      "id": 245,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "total": "100.00",
      "sort_order": 1,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "expenses": [{
      "id": 246,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "total": "100.00",
      "sort_order": 2,
      "created_at": "2015-01-22T19:22:28Z"
    },{...}],

    "tasks": [{
      "id": 300,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 3,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "trips": [{
      "id": 340,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 4,
      "created_at": "2015-01-22T19:22:28Z"
    }]
  }
}

Attributes

Attribute	Description
id	integer Item ID
connection	hash Client details specified by `id` and `name`.
date	string
due_date	string
hash_key	string
state	string An invoice can have different states: `draft`, `viewed`, `sent`, `paid`, `partial`
summary	string
note	string
company_id	string Owner’s Hiveage account `id`
statement_no	string `statement_no` is uniqe. Eg: `IN-001`
payment_options	array Associated payment method keys in an array. Payment method keys: `["cash", "check", "bank_transfer", "paypal"]`
allow_partial_payments	boolean
send_receipts_automatically	boolean
send_reminders	boolean
po_number	string
currency_iso_code	string
currency_symbol	string
billed_total	string
formatted_billed_total	string
sub_total	string
formatted_sub_total	string
total_due	string
formatted_total_due
paid_total	string
formatted_paid_total	string

Adding Tax, Discount and Shipping into invoice

Taxes, discounts and shipping charges can be added to the invoice sub total or line items (items, expenses, mileages and tasks).

Tax

Attributes

Attribute	Description
id	integer
name	string Tax name
key	integer Saved tax reference id
combined_amount_percent	string Fixed or percentage value. Eg: `5.00` or `5.25%`
percentage	boolean If the tax amount is a precentage, this value should be `true`, if not by default `false`.

Discount

Attributes

Attribute	Description
id	integer
name	string Discount name
key	integer Saved discount reference id
combined_amount_percent	string Fixed or percentage value. Eg: `5.00` or `5.25%`
percentage	boolean If the discount amount is a precentage, this value should be `true`, if not by default `false`.

Shipping Amount

Attributes

Attribute	Description
id	integer
name	string Shipping amount name
key	integer Saved shipping amount reference id
combined_amount_percent	string Fixed or percentage value. Eg: `5.00` or `5.25%``
percentage	boolean If the shipping amount is a precentage, this value should be `true`, if not by default `false`.

Create a New Invoice

DEFINITION
POST https://[subdomain].hiveage.com/api/invs

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d invoice[summary]="Invoice summary" \
  -d invoice[date]="2014-01-20" \
  -d invoice[connection_id]="14578" \
  ...
  -d invoice[note]="Invoice note"

EXAMPLE JSON REQUEST BODY
{ 
  "invoice": {
    "connection_id": 14578,
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": 1,
    "send_receipts_automatically": 1,
    "po_number": "PO-number",
    "send_reminders": false,

    "taxes_attributes": [{
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts_attributes": [{
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts_attributes": [{
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "sort_order": 1
    }, {...}],

    "expenses_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "sort_order": 2
    },{...}],

    "tasks_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "sort_order": 3
    }, {...}],

    "trips_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "sort_order": 4
    }]
  }
}

Attributes

Parameter	Description
connection_id	required `connection_id` as specified in the Network section. It may be an individual connection `id` or organization `id`
date	required Invoice date
due_date	required Invoice due date
summary	optional
note	optional
statement_no	required Invoice `statement_no` should be unique
payment_options	optional Associated payment method keys in an array. Payment method keys: `["cash", "check", "bank_transfer", "paypal"]`
allow_partial_payments	optional
send_receipts_automatically	optional
send_reminders	optional
po_number	optional

NOTE: Different types of line items (“Items”, “Expenses”, “Trips” and “Tasks”) can be added as shown in the example JSON request. Taxes, Discounts and Shipping charges could be added to invoice sub total or line items.

Retrieve an Invoice

Retrieve an invoice object with a specified hash_key.

DEFINITION
GET https://[subdomain].hiveage.com/api/invs/[hash_key]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{ 
  "invoice": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "hash_key": "bCbFYNj3RFM2uQ",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "total_due": "0.00",
    "paid_total": "0.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [{
      "id": 3,
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts": [{
      "id": 4,
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts": [{
      "id": 5,
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items": [{
      "id": 245,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "total": "100.00",
      "sort_order": 1,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "expenses": [{
      "id": 246,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "total": "100.00",
      "sort_order": 2,
      "created_at": "2015-01-22T19:22:28Z"
    },{...}],

    "tasks": [{
      "id": 300,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 3,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "trips": [{
      "id": 340,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 4,
      "created_at": "2015-01-22T19:22:28Z"
    }]
  }
}

Arguments

Parameter	Description
hash_key	required The `hash_key` of the invoice object.

Returns

Returns an invoice JSON object if a valid invoice hash_key was provided. Returns an error otherwise.

Update an Invoice

Update an invoice object.

DEFINITION
PUT https://[subdomain].hiveage.com/api/invs/[hash_key]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d invoice[statement_no]="IN-002" \
  -d invoice[summary]="Invoice summary to be updated" \
  -d invoice[connection_id]="53321" \

EXAMPLE RESPONSE
{
  "invoice": {
    "id": 12,
    "connection": { 
      "id": 53321,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "hash_key": "bCbFYNj3RFM2uQ",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "total_due": "0.00",
    "paid_total": "0.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [ {...}],
    "discounts": [{...}],
    "shipping_amounts": [{...}],

    "items": [{...}],
    "expenses": [{...}],
    "tasks": [{...}],
    "trips": [{...}]
  }
}

Attributes

Parameter	Description
connection_id	required `connection_id` as specified in the Network section. It may be your individual connection `id` or organization `id`
date	required Invoice date
due_date	required Invoice due date
summary	optional
note	optional
statement_no	required Invoice `statement_no` should be unique
payment_options	optional Associated payment method keys in an array. Payment method keys: `["cash", "check", "bank_transfer", "paypal"]`
allow_partial_payments	optional
send_receipts_automatically	optional
send_reminders	optional
po_number	optional

Delete an Invoice

Deleting an invoice object will move it to Trash. It will not be deleted permanently. To permanently delete an invoice, the user has to log into Hiveage and delete it manually from the trash.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/invs/[hash_key]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "invoice": {
    "deleted": true,
    "id": "bCbFYNj3RFM2uQ"
  }
}

Arguments

Parameter	Description
id	required The `hash_key` of the invoice to be deleted.

Returns an object with a deleted parameter on success.

List All Invoices

Returns a list of invoices. The invoices are returned sorted alphabetically.

DEFINITION
GET https://[subdomain].hiveage.com/api/invs

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/invs\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "invoices": [{
    "id": 12,
    "connection": { 
      "id": 53321,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "hash_key": "bCbFYNj3RFM2uQ",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "total_due": "0.00",
    "paid_total": "0.00",
    "created_at": "2015-01-22T19:22:28Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter	Description
per_page	optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page	optional Page in the results set
order	optional The list is sorted by `date`, `statement_no`, `state`, and can ordered by `desc` or `asc`. The defaul value is `asc`.

Send Invoice

There are two ways to deliver a message.

i. Delivers an exisiting invoice without specifying any parameters. It will use defalut invoice email template values.

DEFINITION
POST https://[subdomain].hiveage.com/api/invs/[hash_key]/deliver

EXAMPLE REQUEST (i)
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key]/deliver\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \


EXAMPLE REQUEST (ii)
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key]/deliver\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d delivery[recipients]="[{name: 'Peter', email: '[email protected]'}, {name: 'Sam', email: '[email protected]'}]" \
  -d delivery[blind_copies]="[{name: 'Jane', email: '[email protected]'}]" \
  -d delivery[subject]="Message subject" \
  -d delivery[message]="Message content" \
  -d delivery[attachment]="true" \

SAMPLE JSON RESPONSE
{
  "send": "ok",
}

ii. To send a custom email message for an invoice, the following parameters could be set.

Arguments

Parameter	Description
recipients	required Specifies `TO` addresses of the invoice email. Eg: `[{name: 'Peter', email: '[email protected]'}, {name: 'Sam', email: '[email protected]'}]`
blind_copies	required Specifies `BCC` addresses of the invoice email. Eg: `[{name: 'Jane', email: '[email protected]'}]`
subject	required The subject of the invoice email
message	required
attachment	optional If the invoice PDF should be attached, this must be set to `true`; otherwise `false` by default.

Send Invoice Reminder

There are two ways to send an invoice reminder.

i. Delivers an exisiting invoice without specifying any parameters. It will use defalut invoice reminder template values.

DEFINITION
POST https://[subdomain].hiveage.com/api/invs/[hash_key]/reminder

EXAMPLE REQUEST (i)
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key]/reminder\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \


EXAMPLE REQUEST (ii)
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key]/reminder\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d delivery[recipients]="[{name: 'Peter', email: '[email protected]'}, {name: 'Sam', email: '[email protected]'}]" \
  -d delivery[blind_copies]="[{name: 'Jane', email: '[email protected]'}]" \
  -d delivery[subject]="Message subject" \
  -d delivery[message]="Message content" \
  -d delivery[attachment]="true" \

SAMPLE JSON RESPONSE
{
  "send": "ok",
}

ii. You can set all parameters if you wish to send custom emali message to selected invoice.

Arguments

Parameter	Description
recipients	required Specifies `TO` addresses of the reminder email. Eg: `[{name: 'Peter', email: '[email protected]'}, {name: 'Sam', email: '[email protected]'}]`
blind_copies	required Specifies `BCC` addresses of the reminder email. Eg: `[{name: 'Jane', email: '[email protected]'}]`
subject	required The subject of the reminder email
message	required
attachment	optional If the invoice PDF should be attached, this must be set to `true`; otherwise `false` by default.