Table of Contents
Recurring Invoices
/v1/client/id/add_recurring_invoice
Add an invoice for a client. The example adds an invoice with two items.
$ curl -u user:pass -d "first=2013-06-01&mode=DAYMONTH&number=1" \ > -d "description[]=rolls&unit_cost[]=5&quantity[]=12" \ > -d "description[]=cakes&unit_cost[]=120&quantity[]=1" \ > https://api.snapbill.com/v1/client/158958/add_recurring_invoice.json
File: examples/recurring_invoice.txt-1.json -
{
"code": 200,
"type": "item",
"class": "recurring_invoice",
"recurring_invoice": {
"id": 10027,
"xid": "Clw:Ccr",
"state": "active",
"created": "2014-08-22 09:57:40",
"total": "18000.00",
"total_cents": 18000,
"mode": "DAYMONTH",
"weekday": 0,
"number": 1,
"interval": 1,
"first": "2013-06-01 00:00:00",
"last": null,
"next": null,
"lines": [
{
"id": 25545,
"xid": 25545,
"item_name": "",
"description": "rolls",
"quantity": "12.00",
"unit_cost": "5.00",
"unit_cost_cents": 500,
"taxed": true,
"total": "60.00",
"total_cents": 6000
},
{
"id": 25546,
"xid": 25546,
"item_name": "",
"description": "cakes",
"quantity": "1.00",
"unit_cost": "120.00",
"unit_cost_cents": 12000,
"taxed": true,
"total": "120.00",
"total_cents": 12000
}
],
"client": {
"depth": 1,
"id": 158958,
"xid": "Clw:mzu",
"state": "active",
"number": "001",
"name": "test4128",
"account": {
"depth": 1,
"id": 10608,
"xid": "Clw:Clw",
"username": "demo"
},
"cell": "",
"company": "",
"country": {
"code": "ZA",
"iso2": "ZA",
"iso3": "ZAF",
"name": "South Africa"
},
"credit": "0.00",
"credit_cents": 0,
"currency": {
"code": "ZAR",
"format": "R%.2f",
"enabled": true
},
"discount": "0.00",
"email": "",
"firstname": "test4128",
"payment": "netcash",
"payment_method": {
"depth": 2,
"code": "netcash",
"name": "Netcash Collect",
"enabled": true
},
"surname": "",
"totals": {
"unpaid_invoices": "555.58",
"unpaid_invoices_cents": 55558,
"paid_payments": "0.00",
"paid_payments_cents": 0
},
"urls": {
"statement": "https://demo.snapbill.com/statement/Clw:mzu/=NTYxY2UyN2E5",
"payment": "https://demo.snapbill.com/payment/client/Clw:mzu/=YjE5YTM0YWNm"
},
"data": {
"public_city": null,
"public_country": null,
"public_fax": null,
"public_phone": null,
"public_postal": null,
"public_postcode": null,
"public_province": null,
"public_street": null,
"vat_number": null
}
}
}
}
Add Recurring Invoice Parameters
| Name | Availability | Description |
|---|---|---|
| first | add | The first date the recurring invoice is to run on |
| last | add | An optional date after which the recurring invoice should not go off. |
| mode | add | The mode of recurring invoice. This can either be ONCEOFF (only once), DAYWEEK (specific day of each week), DAYMONTH (specific day of each month), or WEEKDAYMONTH (specific weekday of each month). Each of these are explained in detail below. |
| weekday | add | Field required if mode is DAYWEEK or WEEKDAYMONTH. 0 through 6 (Sunday=0, Monday=1, … Sunday=6). |
| number | add | For DAYMONTH this is the day number (6 = 6th), or the week number for WEEKDAYMONTH (2 = 2nd week) |
| interval | add | This is the interval between each recurring invoice. Default value is 1, setting it to 12 on DAYMONTH will send invoices once a year. |
| description[] | add | A description for an invoice item |
| unit_cost[] | add | The cost for a unit of an invoice item |
| quantity[] | add | The amount of units of an invoice item |
The invoice items can be repeated (description, unit_cost, quantity). The first description matches up with the first unit_cost and quantity. Similarly for the 2nd description, etc.
Recurring Modes
ONCEOFF
The recurring invoice will run once, and only once.
DAYWEEK
This recurring mode can be used to invoice once a week. The weekday field specifies which day of the week (Sunday=0, Monday=1, …, Sunday=6). The interval field specifies the number of weeks between charges (i.e. a interval=2 value will charge the invoice every second week.)
DAYMONTH
This mode can be used to invoice clients every number of months. The number field indicates the day of the month to charge. A number=6 value will charge on the 6th day of each month. Number can also be negative in which case it is counted from the end of the month (number=-1 will charge on the last day of each month). The interval field specifies the number of months between charges (i.e. a interval=6 value will charge the invoice every six months.)
WEEKDAYMONTH
The recurring invoice will run on a specified weekday each month. This is useful for invoicing on the first Monday, or the last Friday. The weekday field (similar to DAYWEEK mode) specifies which weekday to charge on, while the number field specifies which week to charge. Interval indicates the number of months between charges. For example weekday=2,number=1,interval=12 will run on the first Tuesday once a yearg
/v1/recurring_invoice/list
List the recurring invoices associated with this account.
Results can optionally be filtered by the filters listed below.
List Recurring Invoices Filters
| Name | Availability | Description |
|---|---|---|
| client_id | get | The client_id of the recurring invoices. |
| page | get | The page of results to return. |
| perpage | get | The number of results per page to return. |
Page Tools
