User Tools

Site Tools


developers:api:invoice

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[0]=rolls&unit_cost[0]=1.12&quantity[0]=13" \
    >   -d "description[1]=chips&unit_cost[1]=20&quantity[1]=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.txt · Last modified: 2016/05/26 14:34 by Jaco van Wyk

Page Tools