API Docs
/
No Results Found
Recurring Invoices

Recurring Invoices

Recurring invoices are invoices that are created and sent to your customers on a recurring schedule.

Attribute

recurring_invoice_id
string
Unique ID of the recurring invoice generated by the server.
recurrence_name
string
Unique name for the recurring profile given by the user. Max-length [100]
reference_number
string
The Order number of the Recurring Invoice.
customer_name
string
Name of the customer to whom the recurring invoice is raised.
is_pre_gst
string
🇮🇳 India
only
Applicable for transactions that fall before july 1, 2017
gst_no
string
🇮🇳 India
only
15 digit GST identification number of the customer.
gst_treatment
string
🇮🇳 India
only
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
tax_treatment
string
GCC only
Choose whether the vat treatment for the contact falls under: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
dz_vat_registered and dz_vat_not_registered supported only for UAE.
vat_treatment
string
🇬🇧 United Kingdom
only
(Optional) VAT treatment for the invoices. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
place_of_supply
string
🇮🇳 India
, GCC only
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
Supported codes for UAE emirates are :
Abu Dhabi - AB,
Ajman - AJ,
Dubai - DU,
Fujairah - FU,
Ras al-Khaimah - RA,
Sharjah - SH,
Umm al-Quwain - UM
Supported codes for the GCC countries are :
United Arab Emirates - AE,
Saudi Arabia - SA,
Bahrain - BH,
Kuwait - KW,
Oman - OM,
Qatar - QA.
customer_id
string
Customer ID of the customer for whom the recurring invoice is raised.
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the invoice is created.
start_date
string
The date on which the recurring invoice starts.
end_date
string
The date on which the recurring invoice expires.
last_sent_date
string
The date at which the last invoice was sent.
next_invoice_date
string
The date at which next invoice is to be sent.
line_items
array
Line items of an invoice.
Show Sub-Attributes arrow
line_item_id
string
The line item id
quantity
int32
Quantity of the item included.
name
string
The name of the line item. max-length [100]
item_total
double
Total rate raised by this item. This would be the multiplicative product of item price and quantity.
sku
string
Enter item's SKU information
product_type
string
Enter goods/services
warehouse_id
string
Enter ID of the warehouse
warehouse_name
string
Name of the warehouse
warehouses
array
Show Sub-Attributes arrow
warehouse_id
string
Enter ID of the warehouse
warehouse_name
string
Name of the warehouse
warehouse_stock_on_hand
string
Available stock in your warehouse.
tags
array
Filter all your reports based on the tag
Show Sub-Attributes arrow
is_tag_mandatory
boolean
Boolean to check if the tag is mandatory
tag_id
string
ID of the reporting tag
tag_name
string
Name of the reporting tag
tag_option_id
string
ID of the reporting tag's option
tag_option_name
string
Name of the reporting tag's option
tax_id
ID of the tax or tax group associated to the recurring invoice.
tax_treatment_code
string
GCC only
Specify reason for using out of scope.
Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction, bahrain_warranty_repair_services and bahrain_others.
Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu, ksa_reimbursed_expense and ksa_house_sales.
project_id
string
ID of the project
project_name
string
Name of the project.
header_name
string
Name of the item header
header_id
string
ID of the item header
billing_address
object
Show Sub-Attributes arrow
address
string
Billing address for the invoice
street2
string
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
shipping_address
object
Show Sub-Attributes arrow
address
string
Billing address for the invoice
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
payment_options
object
Show Sub-Attributes arrow
payment_gateways
array
Show Sub-Attributes arrow
configured
boolean
Boolean check to see if a payment gateway ahs been configured
additional_field1
string
Paypal payment method. Allowed Values: standard and adaptive
gateway_name
string
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
avatax_exempt_no
string
Avalara Integration only
Exemption certificate number of the customer. Max-length [25]
avatax_use_code
string
Avalara Integration only
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]

Example

{ "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "Sujin Kumar", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "vat_treatment": "overseas", "place_of_supply": "TN", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "sku": "LEV-JN-SL-36-GN", "product_type": "goods", "warehouse_id": "", "warehouse_name": "string", "warehouses": [ { "warehouse_id": "", "warehouse_name": "string", "warehouse_stock_on_hand": "" } ], "tags": [ { "is_tag_mandatory": false, "tag_id": 982000000009070, "tag_name": "Location", "tag_option_id": 982000000002670, "tag_option_name": "USA" } ], "tax_id": "903000000000356", "tax_treatment_code": "uae_others", "project_id": 90300000087378, "project_name": "Sample Project", "header_name": "Electronic devices", "header_id": 982000000000670 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_options": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "avatax_exempt_no": "string", "avatax_use_code": "string" }

Create a Recurring Invoice

Creating a new recurring invoice.
oauthscope : ZohoBooks.invoices.CREATE

Arguments

recurrence_name
string
(Required)
Unique name for the recurring profile given by the user. Max-length [100]
reference_number
string
The Order number of the Recurring Invoice.
customer_id
string
(Required)
Customer ID of the customer for whom the recurring invoice is raised.
contact_persons
array
Contact Persons associated with the recurring invoice.
place_of_supply
string
🇮🇳 India
, GCC only
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
Supported codes for UAE emirates are :
Abu Dhabi - AB,
Ajman - AJ,
Dubai - DU,
Fujairah - FU,
Ras al-Khaimah - RA,
Sharjah - SH,
Umm al-Quwain - UM
Supported codes for the GCC countries are :
United Arab Emirates - AE,
Saudi Arabia - SA,
Bahrain - BH,
Kuwait - KW,
Oman - OM,
Qatar - QA.
vat_treatment
string
🇬🇧 United Kingdom
only
(Optional) VAT treatment for the invoices. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
gst_treatment
string
🇮🇳 India
only
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
tax_treatment
string
GCC only
Choose whether the vat treatment for the contact falls under: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
dz_vat_registered and dz_vat_not_registered supported only for UAE.
gst_no
string
🇮🇳 India
only
15 digit GST identification number of the customer.
start_date
string
The date on which the recurring invoice starts.
end_date
string
The date on which the recurring invoice expires.
recurrence_frequency
string
(Required)
The frequency of time interval at which the invoice is to be generated.
repeat_every
integer
The period between every recurrency frequency.
line_items
array
Line items of an invoice.
Show Sub-Attributes arrow
line_item_id
string
The line item id
quantity
int32
Quantity of the item included.
name
string
The name of the line item. max-length [100]
item_total
double
Total rate raised by this item. This would be the multiplicative product of item price and quantity.
product_type
string
Enter goods/services
hsn_or_sac
string
🇮🇳 India
only
Add HSN/SAC code for your goods/services
tags
array
Filter all your reports based on the tag
Show Sub-Attributes arrow
tag_id
string
ID of the reporting tag
tag_option_id
string
ID of the reporting tag's option
warehouse_id
string
Enter ID of the warehouse
tax_id
ID of the tax or tax group associated to the recurring invoice.
tax_treatment_code
string
GCC only
Specify reason for using out of scope.
Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction, bahrain_warranty_repair_services and bahrain_others.
Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu, ksa_reimbursed_expense and ksa_house_sales.
project_id
string
ID of the project
header_name
string
Name of the item header
tax_id
ID of the tax or tax group associated to the recurring invoice.
email
string
Email address of the customer.
billing_address
object
Show Sub-Attributes arrow
address
string
Billing address for the invoice
street2
string
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
shipping_address
object
Show Sub-Attributes arrow
address
string
Billing address for the invoice
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
avatax_use_code
string
Avalara Integration only
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
avatax_exempt_no
string
Avalara Integration only
Exemption certificate number of the customer. Max-length [25]
template_id
string
Unique ID of the recurring invoice template.
payment_terms
integer
Payment terms in days. E.g: 15,30,60. Invoice due date will be calculated based on this.
payment_terms_label
string
Used to overridethe default payment terms label. Default value for 15 days is "Next 15 days".
tax_authority_id
string
🇺🇸 United States
only
Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
tax_exemption_id
string
🇮🇳 India
, 🇺🇸 United States
, 🇦🇺 Australia
, 🇨🇦 Canada
only
Unique ID of the tax exemption.
exchange_rate
string
Exchange rate for the currency associated with the customer.
payment_options
object
Show Sub-Attributes arrow
payment_gateways
array
Show Sub-Attributes arrow
configured
boolean
Boolean check to see if a payment gateway ahs been configured
additional_field1
string
Paypal payment method. Allowed Values: standard and adaptive
gateway_name
string
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
discount
string
Discount applied to the invoice. It can be either in % or in amount. E.g: 12.5% or 190.
is_discount_before_tax
boolean
Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type
string
How the discount is specified. Allowed values: entity_level and item_level.
is_inclusive_tax
boolean
Not applicable 🇺🇸 United States
, 🇨🇦 Canada
Used to specify whether the line item rates are inclusive or exclusive of tax.
item_id
string
Unique string generated for the item for which invoice is to be sent.
name
string
The name of the line item. max-length [100]
description
string
A small description about the item. Max-length [2000]
rate
double
Rate of the line item.
quantity
int32
Quantity of the item included.
unit
string
Unit of the line item. E.g: kgs, Nos.
avatax_tax_code
string
A tax code is a unique label used to group items together.
salesperson_name
string
🇺🇸 United States
, 🇦🇺 Australia
, 🇨🇦 Canada
only
Name of the sales person
shipping_charge
double
Shipping charges applied to the invoice.
adjustment
double
Adjustments made to the invoice.
adjustment_description
string
Customize the adjustment description. E.g: Rounding off.

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/recurringinvoices -X POST -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_id": "903000000000099", "contact_persons": [ "90300000065322" ], "place_of_supply": "TN", "vat_treatment": "overseas", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "gst_no": "22AAAAA0000A1Z5", "start_date": "2016-06-12", "end_date": "2017-06-12", "recurrence_frequency": "weeks", "repeat_every": 2, "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540, "tags": [ { "tag_id": 982000000009070, "tag_option_id": 982000000002670 } ], "warehouse_id": "", "tax_id": "903000000000356", "tax_treatment_code": "uae_others", "project_id": 90300000087378, "header_name": "Electronic devices" } ], "tax_id": "903000000000356", "email": "benjamin.george@bowmanfurniture.com", "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "avatax_use_code": "string", "avatax_exempt_no": "string", "template_id": "90300000001336", "payment_terms": 0, "payment_terms_label": "Next 15 days", "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345", "exchange_rate": "5.5", "payment_options": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "discount": "30%", "is_discount_before_tax": true, "discount_type": "entity level", "is_inclusive_tax": false, "item_id": "90300000081501", "name": "Hard Drive", "description": "prorated amount for items", "rate": 0, "quantity": 1, "unit": "kgs", "avatax_tax_code": " ", "salesperson_name": " ", "shipping_charge": 0, "adjustment": 0, "adjustment_description": "Rounding off" }

Response Example

{ "code": 0, "message": "The recurring invoice has been created.", "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "Sujin Kumar", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "vat_treatment": "overseas", "place_of_supply": "TN", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "sku": "LEV-JN-SL-36-GN", "product_type": "goods", "warehouse_id": "", "warehouse_name": "string", "warehouses": [ { "warehouse_id": "", "warehouse_name": "string", "warehouse_stock_on_hand": "" } ], "tags": [ { "is_tag_mandatory": false, "tag_id": 982000000009070, "tag_name": "Location", "tag_option_id": 982000000002670, "tag_option_name": "USA" } ], "tax_id": "903000000000356", "tax_treatment_code": "uae_others", "project_id": 90300000087378, "project_name": "Sample Project", "header_name": "Electronic devices", "header_id": 982000000000670 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_options": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "avatax_exempt_no": "string", "avatax_use_code": "string" }, "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Recurring Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } }

List all Recurring Invoice

List the details of all recurring invoice.
oauthscope : ZohoBooks.invoices.READ

Query Parameters

recurrence_name
Unique name for the recurring profile given by the user. Max-length [100]
item_name
Search recurring invoices by item name. Variants: item_name_startswith and profileitemname_contains.
item_description
Search recurring invoices by item description. Variants: item_description_startswith and item_description_contains.
customer_name
Name of the customer to whom the recurring invoice is raised.
line_item_id
The line item id
item_id
Unique string generated for the item for which invoice is to be sent.
tax_id
ID of the tax or tax group associated to the recurring invoice.
notes
A short note for the recurring invoice.
start_date
The date on which the recurring invoice starts.
end_date
The date on which the recurring invoice expires.
customer_id
Customer ID of the customer for whom the recurring invoice is raised.
status
Status of the recurring invoice. This can be active, stopped or expired.
filter_by
Filter Recurring invoices by any status or payment expected date.Allowed Values: Status.All, Status.Active, Status.Stopped, Status.Expired
search_text
Search invoices by invoice number or purchase order or customer name. Max-length [100]
sort_column

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/recurringinvoices -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "Details of a recurring invoice is displayed successfully.", "recurring_invoices": [ { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "customer_name": "Sujin Kumar", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" } }, {...}, {...} ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Recurring Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } }

Update Recurring Invoice

Update the recurring invoice.
oauthscope : ZohoBooks.invoices.UPDATE

Arguments

recurrence_name
string
(Required)
Unique name for the recurring profile given by the user. Max-length [100]
reference_number
string
The Order number of the Recurring Invoice.
customer_id
string
(Required)
Customer ID of the customer for whom the recurring invoice is raised.
contact_persons
array
Contact Persons associated with the recurring invoice.
start_date
string
The date on which the recurring invoice starts.
end_date
string
The date on which the recurring invoice expires.
recurrence_frequency
string
(Required)
The frequency of time interval at which the invoice is to be generated.
repeat_every
integer
The period between every recurrency frequency.
place_of_supply
string
🇮🇳 India
, GCC only
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
Supported codes for UAE emirates are :
Abu Dhabi - AB,
Ajman - AJ,
Dubai - DU,
Fujairah - FU,
Ras al-Khaimah - RA,
Sharjah - SH,
Umm al-Quwain - UM
Supported codes for the GCC countries are :
United Arab Emirates - AE,
Saudi Arabia - SA,
Bahrain - BH,
Kuwait - KW,
Oman - OM,
Qatar - QA.
vat_treatment
string
🇬🇧 United Kingdom
only
(Optional) VAT treatment for the invoices. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
gst_treatment
string
🇮🇳 India
only
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
tax_treatment
string
GCC only
Choose whether the vat treatment for the contact falls under: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
dz_vat_registered and dz_vat_not_registered supported only for UAE.
gst_no
string
🇮🇳 India
only
15 digit GST identification number of the customer.
line_items
array
Line items of an invoice.
Show Sub-Attributes arrow
item_id
string
Unique string generated for the item for which invoice is to be sent.
name
string
The name of the line item. max-length [100]
description
string
A small description about the item. Max-length [2000]
rate
double
Rate of the line item.
quantity
int32
Quantity of the item included.
discount
string
Discount applied to the invoice. It can be either in % or in amount. E.g: 12.5% or 190.
tags
array
Filter all your reports based on the tag
Show Sub-Attributes arrow
tag_id
string
ID of the reporting tag
tag_option_id
string
ID of the reporting tag's option
tax_id
ID of the tax or tax group associated to the recurring invoice.
tax_exemption_id
string
🇮🇳 India
, 🇺🇸 United States
, 🇦🇺 Australia
, 🇨🇦 Canada
only
Unique ID of the tax exemption.
tax_treatment_code
string
GCC only
Specify reason for using out of scope.
Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction, bahrain_warranty_repair_services and bahrain_others.
Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu, ksa_reimbursed_expense and ksa_house_sales.
avatax_tax_code
string
A tax code is a unique label used to group items together.
avatax_use_code
string
Avalara Integration only
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
item_total
double
Total rate raised by this item. This would be the multiplicative product of item price and quantity.
product_type
string
Enter goods/services
hsn_or_sac
string
🇮🇳 India
only
Add HSN/SAC code for your goods/services
warehouse_id
string
Enter ID of the warehouse
project_id
string
ID of the project
header_name
string
Name of the item header
header_id
string
ID of the item header
email
string
Email address of the customer.
tax_id
ID of the tax or tax group associated to the recurring invoice.
tax_authority_id
string
🇺🇸 United States
only
Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
payment_options
object
Show Sub-Attributes arrow
payment_gateways
array
Show Sub-Attributes arrow
configured
boolean
Boolean check to see if a payment gateway ahs been configured
additional_field1
string
Paypal payment method. Allowed Values: standard and adaptive
gateway_name
string
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
tax_exemption_id
string
🇮🇳 India
, 🇺🇸 United States
, 🇦🇺 Australia
, 🇨🇦 Canada
only
Unique ID of the tax exemption.
avatax_use_code
string
Avalara Integration only
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
avatax_exempt_no
string
Avalara Integration only
Exemption certificate number of the customer. Max-length [25]

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id} -X PUT -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_id": "903000000000099", "contact_persons": [ "90300000065322" ], "start_date": "2016-06-12", "end_date": "2017-06-12", "recurrence_frequency": "weeks", "repeat_every": 2, "place_of_supply": "TN", "vat_treatment": "overseas", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "gst_no": "22AAAAA0000A1Z5", "line_items": [ { "item_id": "90300000081501", "name": "Hard Drive", "description": "prorated amount for items", "rate": 0, "quantity": 1, "discount": "30%", "tags": [ { "tag_id": 982000000009070, "tag_option_id": 982000000002670 } ], "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "tax_treatment_code": "uae_others", "avatax_tax_code": " ", "avatax_use_code": "string", "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "", "project_id": 90300000087378, "header_name": "Electronic devices", "header_id": 982000000000670 } ], "email": "benjamin.george@bowmanfurniture.com", "tax_id": "903000000000356", "tax_authority_id": "903000006345", "payment_options": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "tax_exemption_id": "903000006345", "avatax_use_code": "string", "avatax_exempt_no": "string" }

Response Example

{ "code": 0, "message": "success", "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "Sujin Kumar", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "vat_treatment": "overseas", "place_of_supply": "TN", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "sku": "LEV-JN-SL-36-GN", "product_type": "goods", "warehouse_id": "", "warehouse_name": "string", "warehouses": [ { "warehouse_id": "", "warehouse_name": "string", "warehouse_stock_on_hand": "" } ], "tags": [ { "is_tag_mandatory": false, "tag_id": 982000000009070, "tag_name": "Location", "tag_option_id": 982000000002670, "tag_option_name": "USA" } ], "tax_id": "903000000000356", "tax_treatment_code": "uae_others", "project_id": 90300000087378, "project_name": "Sample Project", "header_name": "Electronic devices", "header_id": 982000000000670 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_options": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "avatax_exempt_no": "string", "avatax_use_code": "string" } }

Get a Recurring Invoice

Get the details of a recurring invoice.
oauthscope : ZohoBooks.invoices.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}

Response Example

{ "code": 0, "message": "Details of a recurring invoice is displayed successfully.", "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "Sujin Kumar", "customer_id": "903000000000099", "company_name": "ABC Studios", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "vat_treatment": "overseas", "place_of_supply": "TN", "customer_email": "emailid@abcstudios.com", "customer_mobile_phone": 9876543210, "customer_phone": "012-12345678", "photo_url": "https://secure.gravatar.com/avatar/xxxxxxxxxx?&d=mm", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "sku": "LEV-JN-SL-36-GN", "product_type": "goods", "warehouse_id": "", "warehouse_name": "string", "warehouses": [ { "warehouse_id": "", "warehouse_name": "string", "warehouse_stock_on_hand": "" } ], "tags": [ { "is_tag_mandatory": false, "tag_id": 982000000009070, "tag_name": "Location", "tag_option_id": 982000000002670, "tag_option_name": "USA" } ], "tax_id": "903000000000356", "tax_treatment_code": "uae_others", "project_id": 90300000087378, "project_name": "Sample Project", "header_name": "Electronic devices", "header_id": 982000000000670 } ], "paid_invoices_total": 100, "unpaid_invoices_balance": 100, "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_options": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] } }, "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Recurring Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } }

Delete a Recurring Invoice

Delete an existing recurring invoice.
oauthscope : ZohoBooks.invoices.DELETE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id} -X DELETE

Response Example

{ "code": 0, "message": "The recurring invoice is deleted successfully." }

Stop a Recurring Invoice

Stop an active recurring invoice.
oauthscope : ZohoBooks.invoices.CREATE

Arguments

recurring_invoice_id
string
Unique ID of the recurring invoice generated by the server.

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/status/stop -X POST -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "recurring_invoice_id": "90300000072369" }

Response Example

{ "code": 0, "message": "The recurring invoice has been stopped." }

Resume a Recurring Invoice

Resume a stopped recurring invoice.
oauthscope : ZohoBooks.invoices.CREATE

Arguments

recurring_invoice_id
string
Unique ID of the recurring invoice generated by the server.

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/status/resume -X POST -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "recurring_invoice_id": "90300000072369" }

Response Example

{ "code": 0, "message": "The recurring invoice has been resumed." }

Update Recurring Invoice template

Update the pdf template associated with the recurring invoice.
oauthscope : ZohoBooks.invoices.UPDATE

Arguments

recurring_invoice_id
string
Unique ID of the recurring invoice generated by the server.
template_id
string
Unique ID of the recurring invoice template.

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/templates/{template_id} -X PUT -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "recurring_invoice_id": "90300000072369", "template_id": "90300043563547" }

Response Example

{ "code": 0, "message": "The template of the recurring invoice has been updated." }

List Recurring Invoice History

Get the complete history and comments of a recurring invoice.
oauthscope : ZohoBooks.invoices.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/comments

Response Example

{ "code": 0, "message": "The complete history and comments of a recurring invoice are displayed successfully.", "comments": [ { "comment_id": "982000000567019", "recurring_invoice_id": "90300000072369", "comment_description": "Recurring Invoice created", "commented_by_id": "982000000554041", "commented_by": "Sujin Kumar", "comment_type": "system", "operation_type": "Added", "date": "2016-06-05", "date_description": "yesterday", "time": "2:02 AM", "transaction_id": "903000002072369", "transaction_type": "estimate" }, {...}, {...} ] }