User Tools

Site Tools


developers:api:recurring_invoice

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.
developers/api/recurring_invoice.txt · Last modified: 2014/10/18 12:07 by Jaco van Wyk