Recurring invoices

Get recurring templates list

GET /recurring/templates[/frequency/#{frequency}][/name/#{name}][/grand_total_operator/#{grand_total_operator}][/grand_total/#{grand_total}][/recurring_total_operator/#{recurring_total_operator}][/recurring_total/#{recurring_total}]

URI arguments

Argument	Type	Value/Description
frequency	string	A recurring frequency to filter. See the possible values of frequency.
name	string	A name for the recurring template.
grand_total_operator	string	See the possible values of operator.
grand_total	double	The grand total amount.
recurring_total_operator	string	See the possible values of operator.
recurring_total	double	The recurring total amount.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/recurring/templates

XML response example

HTTP Status : 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<templates>
		<template>
			<template_id>3</template_id>
			<template_name>Template Name</template_name>
                        <summary></summary>
			<currency>EUR</currency>
			<grand_total>847.75</grand_total><!-- Total VAT Incl. -->
			<frequency>monthly</frequency>
			<frequency_specified>0</frequency_specified>
			<total_schedules>2</total_schedules>
		</template>
		<template>
			...
		</template>
	</templates>
</xml>

Top

Get a recurring template

GET /recurring/template/id/#{template_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{template_id} of the recurring template you wish to get.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/recurring/template/id/1

XML response example

HTTP Status : 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<template>
		<template_id>1</template_id>
		<user_id>1</user_id>
		<template_name>Template Name</template_name>
		<summary></summary>
		<currency>EUR</currency>
		<total>710</total><!-- Total VAT Excl. -->
		<global_discount_total>0</global_discount_total>
		<global_discount_percentage>0</global_discount_percentage>
		<sub_total>710</sub_total>
		<tax_total>137.2</tax_total>
		<alt_tax_total>0.55</alt_tax_total>
		<tax_name>TVA</tax_name>
		<tax_percentage>19.6</tax_percentage>
		<alt_tax_name>TVA</alt_tax_name>
		<alt_tax_percentage>5.5</alt_tax_percentage>
		<use_tax_inclusive>0</use_tax_inclusive>
		<taxation_mode>simple</taxation_mode>
		<grand_total>847.75</grand_total><!-- Total VAT Incl. -->
		<terms>0</terms>
		<custom_terms></custom_terms>
		<payment>VIR</payment>
		<payment_specified></payment_specified>
		<late_fee>0</late_fee>
		<late_fee_specified>0</late_fee_specified>
		<notes></notes>
		<frequency>monthly</frequency>
		<frequency_specified>0</frequency_specified>
		<cc_tenant>1</cc_tenant>
		<attach_pdf>1</attach_pdf>
		<lines>
			<line>
				<line_id>5</line_id>
				<item_id>11</item_id>
				<line_number>1</line_number>
				<kind>4</kind>
				<qty>1</qty>
				<description>HTC Desire HD A9191 with HTC Sense</description>
				<tax_percentage>19.6</tax_percentage>
				<alt_tax_percentage>0</alt_tax_percentage>
				<unit_price>600</unit_price>
				<reduction_percentage>0</reduction_percentage>
			</line>
			<line>
				...
			</line>
		</lines>
	</template>
</xml>

Top

Create a recurring template

POST /recurring/template

Request fields

Field	Type	Required	Description
template_name	string	yes	Name of the recurring template.
summary	string		A summary of the recurring template (for internal usage).
currency	string		Currency of the invoice. The default is the one from your account settings. See the possible values of currency.
tax_name	string		Name of the tax. The default value is the one from your account settings.
tax_percentage	double		Tax percentage. The default value is the one from your account settings.
alt_tax_name	string		Alternative tax name. The default value is the one from your account settings.
alt_tax_percentage	double		Alternative tax percentage. The default value is the one from your account settings.
use_tax_inclusive	boolean		Define if the unit price of the items include tax. The default value is the one from your account settings.
taxation_mode	string		The default value is the one from your account settings. Must be “compound” to use compound tax calculation.
global_discount_percentage	double		Global discount percentage. Default value is 0.
terms	string		Terms of payment settlement. The default value is the one from your account settings. See the possible values of terms.
payment	string		Payment method. The default value is the one from your account settings. See the possible values of payment.
late_fee	double		Late fee percentage. The default value is the one from your account settings See the possible values of late_fee.
lines	array	yes (at least one line)	Invoice lines.
lines[#{key}][item_id]	integer		The #{item_id} of the inventory item associated with the line. If provided, description and unit_price fields are not required.
lines[#{key}][kind]	integer		Line kind. Default value is “1” for “Service”. See the possible values of kind.
lines[#{key}][qty]	double		Item quantity. Equals 1 by default.
lines[#{key}][description]	string	yes	Item description.
lines[#{key}][tax]	boolean		Apply tax. Equals FALSE if not provided.
lines[#{key}][alt_tax]	boolean		Apply alternative tax. Equals FALSE if not provided.
lines[#{key}][unit_price]	double	yes	Item price.
lines[#{key}][reduction_percentage]	double		Reduction percentage for the line.
notes	string		The notes you wish to add to the generated invoice (all notes appear on the document). The default value is the one from your account settings.
frequency	string		The sending frequency of the recurring invoice. The default value us “monthly” for “each months”. See the possible values of frequency.
cc_tenant	boolean		The account owner gets the e-mail sent when the recurring invoice is sent. Is FALSE if not provided.
attach_pdf	boolean		Attach the PDF when the recurring invoice is sent. Is FALSE if not provided.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-d "currency=EUR&tax_name=TVA&tax_percentage=19.6&alt_tax_name=TVA&alt_tax_percentage=5.5&taxation_mode=simple&global_discount_percentage=0&terms=30END&payment=VIR&late_fee=0&lines[0][description]=Recurring invoice line 1&lines[0][unit_price]=10&lines[0][qty]=1&lines[1][description]=Recurring invoice line 2&lines[1][unit_price]=20&lines[1][qty]=2&notes=Recurring invoice notes&frequency=weekly&attach_pdf=1"\
https://#{subdomain}.iscriba.com/api/recurring/template

XML response example

HTTP Status: 201 Created

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<template_id>1</template_id>
</xml>

Top

Modify a recurring template

PUT /recurring/template/id/#{template_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{template_id} of the recurring template you wish to modify.

Request fields

Same as create a recurring template except no field is required. All fields not included in the request remain unchanged.

Warning: for fields of type array, you must provide the full array if you want to add, edit or delete an array element.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X PUT\
-d "frequency=yearly"\
https://#{subdomain}.iscriba.com/api/recurring/template/id/1

XML response example

HTTP Response: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<template_id>1</template_id>
</xml>

Top

Delete a recurring template

DELETE /recurring/template/id/#{template_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{template_id} of the recurring template you wish to delete.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X DELETE https://#{subdomain}.iscriba.com/api/recurring/template/id/1

XML response example

HTTP Response: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<template_id>1</template_id>
</xml>

Top

Get recurring schedules list

GET /recurring/schedules/[/template_id/#{template_id}][/client_id/#{client_id}]

URI arguments

Argument	Type	Required	Value/Description
template_id	integer		The #{template_id} of the recurring template to filter.
client_id	integer		The #{client_id} of the associated client to filter.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/recurring/schedules/template_id/9

XML response example

HTTP Status: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<schedules>
		<schedule>
			<schedule_id>4</schedule_id>
			<template_id>9</template_id>
			<client_id>26</client_id>
			<client_name>Client Name</client_name>
			<recipients>
				<recipient>37</recipient>
				<recipient>38</recipient>
			</recipients>
			<start_billing_on>2011-01-31</start_billing_on>
			<stop_billing_on>0000-00-00</stop_billing_on>
			<occurrences>0</occurrences>
			<occurrences_past>1</occurrences_past>
			<last_run>2011-02-02</last_run>
		</schedule>
		<schedule>
			...
		</schedule>
	</schedules>
</xml>

Top

Get a recurring schedule

GET /recurring/schedule/id/#{schedule_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{schedule_id} of the recurring schedule you wish to get.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/recurring/schedule/id/1

XML response examples

HTTP Status: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<schedule>
		<schedule_id>2</schedule_id>
		<template_id>3</template_id>
		<client_id>26</client_id>
		<client_name>Client Name</client_name>
		<recipients>
			<recipient>37</recipient>
		</recipients>
		<start_billing_on>2011-01-25</start_billing_on>
		<stop_billing_on>0000-00-00</stop_billing_on>
		<occurrences>0</occurrences>
		<occurrences_past>2</occurrences_past>
		<last_run>2011-03-10</last_run>
	</schedule>
</xml>

Top

Create a recurring schedule

POST /recurring/schedule

Request fields

Field	Type	Required	Description
template_id	integer	yes	The #{template_id} of the recurring template used by the recurring schedule.
client_id	integer	yes	The #{client_id} of the client for which you create the recurring invoice.
recipients	array		The recipients of the recurring invoice.
recipients[#{key}]	integer		The #{user_id} of a user that will receive the invoice.
start_billing_on	string	yes	The date on which the recurring invoice will start being generated. Cannot be earlier than the current date.
stop_billing_on	string		The date on which the recurring invoice will stop being generated. Cannot be earlier than the current date.
occurrences	integer		The number of occurrences before stopping the generation of the recurring invoice.

If stop_billing_on and occurrences are not provided, the recurring schedule is unlimited in time.
If stop_billing_on is provided, the recurring schedule stop at the provided date.
If occurrences is provided, the recurring schedule stop after the number of occurences.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-d "template_id=1&client_id=12&recipients[0]=5&recipients[1]=8&start_billing_on=2011-03-14&occurrences=6"\
https://#{subdomain}.iscriba.com/api/recurring/schedule

XML response example

HTTP Status: 201 Created

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<schedule_id>1</schedule_id>
</xml>

Top

Modify a recurring schedule

PUT /recurring/schedule/id/#{schedule_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	THe #{schedule_id} of the recurring schedule you wish to modify.

Request fields

Same as create a recurring schedule except no field is required. All fields not included in the request remain unchanged. Date and client_id fields are not taken into account.

Warning: for fields of type array, you must provide the full array if you want to add, edit or delete an array element.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X PUT\
-d "recipients[0]=38"\
https://#{subdomain}.iscriba.com/api/recurring/schedule/id/1

XML response example

HTTP Response: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<schedule_id>1</schedule_id>
</xml>

Top

Delete a recurring schedule

DELETE /recurring/schedule/id/#{schedule_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{schedule_id} of the recurring schedule you wish to delete.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X DELETE https://#{subdomain}.iscriba.com/api/recurring/schedule/id/1

XML response example

HTTP Response: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<schedule_id>1</schedule_id>
</xml>

Top