Recurring Invoices

The Recurring Invoice Object

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

EXAMPLE OBJECT

{
  "recurring_invoie": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "recurring_method": "save_draft", 
    "next_billing_date": "2015-10-18",
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "iteration_no": 2,
    "due_date_options": 15,
    "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",
    "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 shown by id and name.
recurring_method string There are three recurring methods: save_draft, auto_send, auto_bill.
start_date string The date to generate the first invoice when this recurring profile is started.
next_billing_date string The date to generate the next invoice from this recurring profile.
profile_name string Profile name is required to indentify the recurring profile.
profile_no string The Profile ID will be used to create a separate invoice number sequence for this recurring invoice profile. If you leave this field blank, each invoice generated by this recurring profile will be assigned the next available number on your main invoice number sequence.
occurrences integer Enter number of occurrences to repeat. You may enter 0 to repeat forever.
interval_unit string There are four type of intervals available: days, weeks, months, years
interval integer Number of interval units
due_date_options integer Number of days the invoice should be due in, after being generated by the recurring profile.
hash_key string
state string Invoice has different type of states: draft, scheduled, pending, active, completed, closed.
summary string
note string
company_id string Owner’s Hiveage account id
payment_options array Associated payment method keys in an array. Payment method keys: ["cach", "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

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 Recurring Invoice

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

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/rinv/ \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d recurring_invoice[summary]="Invoice summary"\
  -d recurring_invoice[connection_id]="14578"\
  -d recurring_invoice[recurring_method]="save_draft"\
  -d recurring_invoice[start_date]="2015-02-30"\
  -d recurring_invoice[profile_name]="RP-bill"\
  -d recurring_invoice[occurrences]=5\
  -d recurring_invoice[interval_unit]="years"\
  -d recurring_invoice[interval]=4\
  ...
  -d recurring_invoice[note]="Invoice note"

EXAMPLE JSON REQUEST BODY
{
  "recurring_invoice": {
    "connection_id": 14578,
    "recurring_method": "save_draft", 
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "due_date_options": 15,
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "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.
recurring_method string There are three recurring methods: save_draft, auto_send, auto_bill.
start_date string The date to generate the first invoice when this recurring profile is started. This cannot be updated after the first invoice is generated.
profile_name string Profile name is required to indentify after save into the list.
profile_no string The Profile ID will be used to create a separate invoice number sequence for this recurring invoicing schedule. If you leave this field blank, each invoice generated by this recurring schedule will be assigned the next available number on your main invoice number sequence.
occurrences integer Enter number of occurrences to repeat. You may enter 0 to repeat forever.
interval_unit string There are four type of intervals available: days, weeks, months, years
interval integer Number of interval units
due_date_options integer Number of days the invoice should be due in, after being generated by the recurring profile.
summary optional
note optional
payment_options optional Associated payment method keys in an array. Payment method keys: [“cach”, “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 a Recurring Invoice

Retrieve a recurring invoice object with a specified hash_key.

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

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

EXAMPLE RESPONSE
{ 
  "recurring_invoice": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "recurring_method": "save_draft", 
    "next_billing_date": "2015-10-18",
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "iteration_no": 0,
    "due_date_options": 15,
    "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",
    "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 recurring invoice object.

Returns

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

Update a Recurring Invoice

Update a recurring invoice object.

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

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/rinv/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d recurring_invoice[summary]="Invoice summary"\
  -d recurring_invoice[connection_id]="14578"\
  -d recurring_invoice[recurring_method]="save_draft"\
  -d recurring_invoice[next_billing_date]="2015-02-30"\
  -d recurring_invoice[occurrences]=5\
  -d recurring_invoice[interval]="1"\
  -d recurring_invoice[interval_unit]="years"\
  ...
  -d recurring_invoice[note]="Invoice note"

EXAMPLE RESPONSE
{
  "recurring_invoice": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "recurring_method": "save_draft", 
    "next_billing_date": "2015-10-18",
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "iteration_no": 0,
    "due_date_options": 15,
    "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",
    "created_at": "2015-01-22T19:22:28Z",

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

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

Attributes

Parameter Description
connection_id required as specified in the Network section. It may be an individual connection ID or organization ID
recurring_method string There are three recurring methods: save_draft, auto_send, auto_bill.
next_billing_date string The date to generate the next invoice from this recurring profile once its active.
profile_name string Profile name is required to indentify the recurring profile.
profile_no string The Profile ID will be used to create a separate invoice number sequence for this recurring invoicing schedule. If you leave this field blank, each invoice generated by this recurring schedule will be assigned the next available number on your main invoice number sequence.
occurrences integer Enter number of occurrences to repeat. You may enter 0 to repeat forever.
interval_unit string There are four type of intervals available: days, weeks, months, years
interval integer Number of interval units
due_date_options integer Number of days the invoice should be due in, after being generated by the recurring profile.
summary optional
note optional
payment_options optional Associated payment method keys in an array. Payment method keys: ["cach", "check", "bank_transfer", "paypal"]
allow_partial_payments optional
send_receipts_automatically optional
send_reminders optional
po_number optional

Delete a Recurring Invoice

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

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

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

SAMPLE JSON RESPONSE
{
  "recurring_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 Recurring Invoices

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

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

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

SAMPLE JSON RESPONSE
{ 
  "recurring_invoices": [{
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "recurring_method": "save_draft", 
    "next_billing_date": "2015-10-18",
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "iteration_no": 0,
    "due_date_options": 15,
    "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",
    "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 results set
order optional The list has been ordered by profile_name, next_billing_date, state, interval_unit and created_at, and can be ordered by desc or asc. The defaul value is asc.

Invoice Activities

Returns a list of generated invoices for one particular recurring invoice. The invoices are returned sorted created_at date.

DEFINITION
GET https://[subdomain].hiveage.com/api/rinv/q00MYh2dywH6RA/invoices

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/rinv/q00MYh2dywH6RA/invoices\
  -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 results set
order optional The list has been ordered by created_at.