developers:api:invoice
This is an old revision of the document!
Table of Contents
Invoices
/v1/client/id/add_invoice
Add an invoice for a client. The example adds an invoice with two items.
$ curl -u user:pass -d "date=2013-01-07" \ > -d "description[]=rolls&unit_cost[]=1.12&quantity[]=13" \ > -d "description[]=chips&unit_cost[]=20&quantity[]=1" \ > https://api.snapbill.com/v1/client/158958/add_invoice.json
File: examples/invoice.txt-1.json -
{
"code": 200,
"type": "item",
"class": "invoice",
"invoice": {
"id": 1055399,
"xid": "Clw:EBqn",
"created": "2014-08-22 09:56:13",
"type": "invoice",
"state": "unpaid",
"po_number": "",
"date": "2014-08-22",
"due_date": "2014-08-22",
"name": "Invoice 001/0013",
"number": "001/0013",
"currency": {
"code": "ZAR",
"format": "R%.2f",
"enabled": true
},
"subtotal": "34.56",
"subtotal_cents": 3456,
"taxes": [],
"discount": "0.00",
"total": "34.56",
"total_cents": 3456,
"lines": [
{
"id": 1898304,
"xid": 1898304,
"item_name": "",
"description": "rolls",
"unit_cost": "1.12",
"unit_cost_cents": 112,
"quantity": "13.00",
"total": "14.56",
"total_cents": 1456,
"taxed": true,
"package": null,
"term": null
},
{
"id": 1898305,
"xid": 1898305,
"item_name": "",
"description": "chips",
"unit_cost": "20.00",
"unit_cost_cents": 2000,
"quantity": "1.00",
"total": "20.00",
"total_cents": 2000,
"taxed": true,
"package": null,
"term": null
}
],
"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": "435.90",
"unpaid_invoices_cents": 43590,
"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
}
},
"urls": {
"view": "https://demo.snapbill.com/invoice/Clw:EBqn/=MzU2NWE1MTUy",
"payment": "https://demo.snapbill.com/payment/invoice/Clw:EBqn/=NDI1ODEzYzIw"
}
}
}
Add Invoice Parameters
| Name | Availability | Description |
|---|---|---|
| type | add | The type of invoice to generate. The default is invoice. You can specify either quote, invoice or credit. |
| state | add | The state of the invoice. The default is unpaid. You can specify either draft, unpaid, quote or credit. |
| date | add | The due date shown on the invoice. This field is required. |
| discount | add | |
| po_number | add | An optional purchase number to show for the invoice. This field is not required. |
| 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.
/v1/client/id/add_recurring_invoice
Add a recurring invoice to the client.
/v1/client/id/generate_invoice
Generate a single invoice for a given client
$ curl -u user:pass -d "" \ > https://api.snapbill.com/v1/client/158958/generate_invoice.json
File: examples/invoice.txt-2.json -
{
"code": 200,
"type": "item",
"class": "invoice",
"invoice": {
"id": 1055400,
"xid": "Clw:EBqo",
"created": "2014-08-22 09:56:24",
"type": "invoice",
"state": "unpaid",
"po_number": "",
"date": "2014-08-22",
"due_date": "2014-08-22",
"name": "Invoice 001/0014",
"number": "001/0014",
"currency": {
"code": "ZAR",
"format": "R%.2f",
"enabled": true
},
"subtotal": "119.68",
"subtotal_cents": 11968,
"taxes": [],
"discount": "0.00",
"total": "119.68",
"total_cents": 11968,
"lines": [
{
"id": 1898306,
"xid": 1898306,
"item_name": "",
"description": "Pancake Delivery: Delicious Pancakes Setup Fee",
"unit_cost": "50.00",
"unit_cost_cents": 5000,
"quantity": "1.00",
"total": "50.00",
"total_cents": 5000,
"taxed": true,
"package": "Delicious Pancakes",
"term": null,
"service": {
"id": 155688,
"xid": "Clw:mAo",
"state": "active",
"name": "Pancake Delivery",
"username": null,
"created": "2014-08-22 09:55:19",
"renewal": "2014-09-01 00:00:00",
"package": {
"depth": 2,
"id": 25756,
"name": "Delicious Pancakes",
"setup": "50.00",
"setup_cents": 5000,
"terms": [
{
"type": "daymonth",
"day": 1,
"interval": 1,
"description": "Monthly",
"fee": "240.00",
"fee_cents": 24000
}
],
"currency": {
"code": "ZAR",
"format": "R%.2f",
"enabled": true
},
"service_type": {
"id": 596,
"xid": "Clw:JU",
"name": "Pancake Delivery"
},
"flags": {
"hide-signup": false,
"hide-all": false
},
"state": "active",
"available": false
},
"term": 1,
"service_type": {
"id": 596,
"xid": "Clw:JU",
"name": "Pancake Delivery"
},
"client": {
"depth": 2,
"id": 158958,
"xid": "Clw:mzu",
"state": "active",
"number": "001",
"name": "test4128"
},
"variables": [],
"data": {
"created": "2014-08-22 09:55:19",
"package_name": "Delicious Pancakes",
"renewal": "2014-09-01 00:00:00",
"term": 1
}
}
},
{
"id": 1898307,
"xid": 1898307,
"item_name": "",
"description": "Pancake Delivery: Delicious Pancakes Prorated Fee (Rest of August)",
"unit_cost": "69.68",
"unit_cost_cents": 6968,
"quantity": "1.00",
"total": "69.68",
"total_cents": 6968,
"taxed": true,
"package": "Delicious Pancakes",
"term": null,
"service": {
"id": 155688,
"xid": "Clw:mAo",
"state": "active",
"name": "Pancake Delivery",
"username": null,
"created": "2014-08-22 09:55:19",
"renewal": "2014-09-01 00:00:00",
"package": {
"depth": 2,
"id": 25756,
"name": "Delicious Pancakes",
"setup": "50.00",
"setup_cents": 5000,
"terms": [
{
"type": "daymonth",
"day": 1,
"interval": 1,
"description": "Monthly",
"fee": "240.00",
"fee_cents": 24000
}
],
"currency": {
"code": "ZAR",
"format": "R%.2f",
"enabled": true
},
"service_type": {
"id": 596,
"xid": "Clw:JU",
"name": "Pancake Delivery"
},
"flags": {
"hide-signup": false,
"hide-all": false
},
"state": "active",
"available": false
},
"term": 1,
"service_type": {
"id": 596,
"xid": "Clw:JU",
"name": "Pancake Delivery"
},
"client": {
"depth": 2,
"id": 158958,
"xid": "Clw:mzu",
"state": "active",
"number": "001",
"name": "test4128"
},
"variables": [],
"data": {
"created": "2014-08-22 09:55:19",
"package_name": "Delicious Pancakes",
"renewal": "2014-09-01 00:00:00",
"term": 1
}
}
}
],
"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
}
},
"urls": {
"view": "https://demo.snapbill.com/invoice/Clw:EBqo/=Y2RjNzQ5MDVh",
"payment": "https://demo.snapbill.com/payment/invoice/Clw:EBqo/=ZmMzMzMyN2M1"
}
}
}
/v1/invoice/id/get
$ curl -u user:pass -d "" \ > https://api.snapbill.com/v1/invoice/1055387/get.json
File: examples/invoice.txt-3.json -
{
"code": 200,
"type": "list",
"page": 1,
"numpages": 7,
"class": "invoice",
"list": [
{
"id": 1055387,
"xid": "Clw:EBqb",
"created": "2014-08-21 16:25:34",
"type": "invoice",
"state": "pending",
"po_number": "",
"date": "2014-08-21",
"due_date": "2014-08-21",
"name": "Pending invoice 001/0001",
"number": "001/0001",
"currency": {
"code": "ZAR",
"format": "R%.2f",
"enabled": true
},
"subtotal": "50.00",
"subtotal_cents": 5000,
"taxes": [],
"discount": "0.00",
"total": "50.00",
"total_cents": 5000,
"lines": [
{
"id": 1898286,
"xid": 1898286,
"item_name": "",
"description": "Sample",
"unit_cost": "50.00",
"unit_cost_cents": 5000,
"quantity": "1.00",
"total": "50.00",
"total_cents": 5000,
"taxed": true,
"package": null,
"term": null,
"recurring_invoice": {
"id": 10016,
"xid": "Clw:Ccg",
"state": "disabled",
"created": "2014-08-21 16:23:40",
"total": "5000.00",
"total_cents": 5000,
"mode": "ONCEOFF",
"weekday": null,
"number": null,
"interval": null,
"first": "2014-08-21 00:00:00",
"last": "2014-08-21 00:00:00",
"next": null,
"lines": [
{
"id": 25533,
"xid": 25533,
"item_name": "",
"description": "Sample",
"quantity": "1.00",
"unit_cost": "50.00",
"unit_cost_cents": 5000,
"taxed": true,
"total": "50.00",
"total_cents": 5000
}
],
"client": {
"depth": 2,
"id": 158958,
"xid": "Clw:mzu",
"state": "active",
"number": "001",
"name": "test4128"
}
}
}
],
"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
}
},
"urls": {
"view": "https://demo.snapbill.com/invoice/Clw:EBqb/=MGYyZGNkZWNl",
"payment": "https://demo.snapbill.com/payment/invoice/Clw:EBqb/=NjQ5NTg5MTNk"
}
},
{
"id": 1055397,
"xid": "Clw:EBql",
"created": "2014-08-22 09:51:17",
"type": "invoice",
"state": "unpaid",
"po_number": "",
"date": "2014-08-22",
"due_date": "2014-08-22",
"name": "Invoice 001/0011",
"number": "001/0011",
"currency": {
"code": "ZAR",
"format": "R%.2f",
"enabled": true
},
"subtotal": "34.56",
"subtotal_cents": 3456,
"taxes": [],
"discount": "0.00",
"total": "34.56",
"total_cents": 3456,
"lines": [
{
"id": 1898296,
"xid": 1898296,
"item_name": "",
"description": "rolls",
"unit_cost": "1.12",
"unit_cost_cents": 112,
"quantity": "13.00",
"total": "14.56",
"total_cents": 1456,
"taxed": true,
"package": null,
"term": null
},
{
"id": 1898297,
"xid": 1898297,
"item_name": "",
"description": "chips",
"unit_cost": "20.00",
"unit_cost_cents": 2000,
"quantity": "1.00",
"total": "20.00",
"total_cents": 2000,
"taxed": true,
"package": null,
"term": null
}
],
"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
}
},
"urls": {
"view": "https://demo.snapbill.com/invoice/Clw:EBql/=NWZiNGQ4ZGQ1",
"payment": "https://demo.snapbill.com/payment/invoice/Clw:EBql/=MDI3OGY2NzAy"
}
}
]
}
/v1/invoice/id/pdf
Retrieve the invoice rendered as a PDF.
/v1/invoice/id/html
Retrieve the invoice rendered in HTML.
Parameter listing
| Name | Availability | Description | |
|---|---|---|---|
| depth | get | The depth parameter signals the amount of data for the invoice that was provided. depth=0 is the highest level that provides full detail. | |
| id | get | The id of the invoice in the system. This is guaranteed to be unique only over a single account. | |
| xid | get | The xid of the invoice in the system. This is guaranteed to be unique over all accounts. | |
| created | get | The date at which the invoice was created. In the format YYYY-MM-DD HH:MM:SS. | |
| type | add | get | The type of invoice object. Either “invoice”, “quote”, “credit” (Credit Note) or “debit” (Debit Note). |
| state | get | The current state of the invoice | |
| date | get | The date listed on the invoice. This is usually the same as the created date, however it is different when invoices are generated ahead of time. e.g. Created:February 23rd, Date: March 1st, Due Date: March 15th. | |
| due_date | get | The date at which the invoice is due. | |
| name | get | A neatly formatted name for the invoice, including both its state and number. | |
| number | get | The unique (per account) number of the invoice. This is not strictly digits only, for example “INV002/15” is valid. | |
| po_number | add | get | An optional purchase number to show for the invoice. |
| currency | get | A currency object the invoice was charged in. | |
| subtotal | get | The subtotal listed on the invoice (pre-tax+discount) as a string. | |
| subtotal_cents | get | The subtotal given as an integer number of cents. | |
| taxes | get | An array of different taxes applied to the invoice | |
| ↳ name | get | A short name for the given tax | |
| ↳ percent | get | The percentage applied for this tax | |
| ↳ operation | get | Either “add” or “subtract” indicating whether how the tax affects the total. | |
| discount | add | get | A string indicating the discount that was applied on the invoice |
| total | get | The total value of the invoice after discounts/tax as a string. | |
| total_cents | get | The total value as an integer number of cents. | |
| lines | get | An array of all the invoice lines | |
| ↳ id | get | The id of the invoice line (unique per account) | |
| ↳ xid | get | The xid of the line in the system. This is guaranteed to be unique over all accounts. | |
| ↳ item_name | get | The item name for the line. | |
| ↳ description | add | get | The description displayed on the invoice |
| ↳ unit_cost | add | get | The cost per unit of the line as a string |
| ↳ unit_cost_cents | get | The cost per unit of the line as an integer number of cents. | |
| ↳ quantity | add | get | The quantity for the invoice line |
| ↳ total | get | The total of the given line (tax included) as a string | |
| ↳ total_cents | get | The total as an integer number of cents | |
| ↳ package | get | If the line is linked to a service, the package of that service at the time of generating the invoice. | |
| ↳ term | get | If the line is linked to a service, the term of that service at the time of generating the invoice (or null for setup charges). | |
| client | get | A client object that the invoice was generated for. | |
/v1/invoice/list
List all the invoices associated with this account.
Results can optionally be filtered by the filters listed below.
$ curl -u user:pass -d "perpage=2" \ > https://api.snapbill.com/v1/invoice/list.json
File: examples/invoice.txt-4.json -
{
"code": 200,
"type": "item",
"class": "invoice",
"invoice": {
"id": 1055387,
"xid": "Clw:EBqb",
"created": "2014-08-21 16:25:34",
"type": "invoice",
"state": "pending",
"po_number": "",
"date": "2014-08-21",
"due_date": "2014-08-21",
"name": "Pending invoice 001/0001",
"number": "001/0001",
"currency": {
"code": "ZAR",
"format": "R%.2f",
"enabled": true
},
"subtotal": "50.00",
"subtotal_cents": 5000,
"taxes": [],
"discount": "0.00",
"total": "50.00",
"total_cents": 5000,
"lines": [
{
"id": 1898286,
"xid": 1898286,
"item_name": "",
"description": "Sample",
"unit_cost": "50.00",
"unit_cost_cents": 5000,
"quantity": "1.00",
"total": "50.00",
"total_cents": 5000,
"taxed": true,
"package": null,
"term": null,
"recurring_invoice": {
"id": 10016,
"xid": "Clw:Ccg",
"state": "disabled",
"created": "2014-08-21 16:23:40",
"total": "5000.00",
"total_cents": 5000,
"mode": "ONCEOFF",
"weekday": null,
"number": null,
"interval": null,
"first": "2014-08-21 00:00:00",
"last": "2014-08-21 00:00:00",
"next": null,
"lines": [
{
"id": 25533,
"xid": 25533,
"item_name": "",
"description": "Sample",
"quantity": "1.00",
"unit_cost": "50.00",
"unit_cost_cents": 5000,
"taxed": true,
"total": "50.00",
"total_cents": 5000
}
],
"client": {
"depth": 2,
"id": 158958,
"xid": "Clw:mzu",
"state": "active",
"number": "001",
"name": "test4128"
}
}
}
],
"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
}
},
"urls": {
"view": "https://demo.snapbill.com/invoice/Clw:EBqb/=MGYyZGNkZWNl",
"payment": "https://demo.snapbill.com/payment/invoice/Clw:EBqb/=NjQ5NTg5MTNk"
}
}
}
List Invoices Filters
| Name | Availability | Description |
|---|---|---|
| client_id | get | The id of the clients. |
| page | get | The page of results to return. |
| perpage | get | The number of results per page to return. |
developers/api/invoice.1413617879.txt.gz · Last modified: 2014/10/18 07:37 by Jaco van Wyk
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
