Customers
A customer object allows you to keep track of all customer related information.
Download Customers OpenAPI Document
End Points
Create a customer
List all customers
Update a customer
Retrieve a customer
Delete a customer
Retrieve a customer Using CRM Reference
List of transactions
Mark as active
Mark as inactive
Attribute
customer_id
string
Unique ID generated by the server. This is used as identifier.
display_name
string
Name of the customer which will be displayed in the interface and invoices.
salutation
string
Salutation of the customer.
first_name
string
First name of the customer.
last_name
string
Last name of the customer.
email
string
Email address of the customer.
tags
array
tag_option_id
long
Id of the Tag Option
is_tag_mandatory
string
tag_name
string
tag_id
long
ID of the Tag
tag_option_name
string
company_name
string
Registered name of the company the customer represents.
phone
string
Customer's landline or fixed-line number.
mobile
string
Customer's mobile phone number.
website
string
Customer's website if any.
is_portal_enabled
boolean
Is Client portal enabled for the customer.
department
string
Customer's department.
designation
string
Customer's designation.
billing_address
object
Customer's billing address object. It contains
attention,street, city, state,zip,country, state_code and fax. attention
string
Attention of the customer's billing address.
street
string
Street of the customer's billing address.
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.
state_code
string
State Code of the Customer's billing address. Find their region's code here
fax
string
Fax number for the customer's billing address.
shipping_address
object
Customer's shipping address object. It contains
attention,street, city, state,zip,country, state_code and fax. attention
string
Attention of the customer's shipping address.
street
string
Name of the street of the customer's shipping address.
city
string
Name of the city of the customer's shipping address.
state
string
Name of the state of the customer's shipping address.
zip
string
Zip code of the customer's shipping address.
country
string
Country name of the customer's shipping address.
state_code
string
State Code of the customer's shipping address. Find their region's code here
fax
string
Fax number of the customer's shipping address.
currency_code
string
, default is currency_code chosen in organization profile settings
Currency code of the currency in which the customer wants to pay. If currency_code is not specified here, the currency chosen in your Zoho Billing organization will be used for billing.
currency_id
string
Currency ID of the customer's currency.
ach_supported
boolean
, default is false
Set to true if ACH payment is supported for the customer.
twitter
string
Twitter profile of the customer.
facebook
string
Facebook profile of the customer.
skype
string
Skype ID of the customer
notes
string
A short note about the customer.
gst_no
string
India GST
only
GSTIN Number for the customer.
gst_treatment
string
India GST
only
GST Treatment for the customer.
Allowed values for
Allowed values for
gst_treatment : business_gst, business_none, consumer, overseasbusiness_gst - For a GST Registered business owner. business_none - For a GST unregistered business owner. consumer - For a consumer. overseas - Customer for whom you export your goods/services. tax_reg_no
string
🇲🇽
Mexico
only
12 digit Tax Registration number of a contact with Tax treatment as
home_country_mexico, border_region_mexico, non_mexico. Consumers generic RFC: XAXX010101000, Overseas generic RFC: XEXX010101000 tds_tax_id
string
🇲🇽
Mexico
only
ID of the TDS tax.
tax_treatment
string
🇲🇽
Mexico
only
VAT treatment of the contact.Allowed Values:
home_country_mexico (A business that is located within MX)border_region_mexico (A business that is located in the northern and southern border regions in MX)non_mexico (A business that is located outside MX). tax_regime
string
🇲🇽
Mexico
only
Tax Regime of the contact.Allowed Values:
general_legal_person, legal_entities_non_profit, resident_abroad, production_cooperative_societies, agricultural_livestock, optional_group_of_companies, coordinated, simplified_trust, wages_salaries_income, lease, property_disposal_acquisition, other_income, resident_abroad, divident_income, individual_business_professional, interest_income, income_obtaining_price, no_tax_obligation, tax_incorporation, income_through_technology_platform, simplified_trust. is_tds_registered
boolean
🇲🇽
Mexico
only
Boolean to check if tax is registered.
place_of_contact
string
India GST
only
Customer's place of contact.
price_precision
integer
The Price Precision of the selected currency for the customer
unused_credits
double
Customer's unused credits.
outstanding
double
Amount that has to be paid to the customer.
status
string
Status of the customer. It can either be
active or inactive. custom_fields
array
Additional fields for customers.
index
integer
Index of the custom field. It can hold any value from 1 to 10.
value
string
Value of the custom field.
data_type
string
Data type of the custom field.
label
string
Label of the custom field.
zcrm_account_id
string
This is the Zoho CRM account id of the customer if the customer is synced with the accounts in Zoho CRM.
zcrm_contact_id
string
This is the Zoho CRM contact id of the customer if the customer is synced with the contacts in Zoho CRM.
updated_time
string
Time at which the customer details were last updated.
created_time
string
Time at which the customer was created.
source
string
Denotes how the customer was created.
payment_terms
integer
Net payment term for the customer.
payment_terms_label
string
Text field of payment terms.
is_linked_with_zohocrm
boolean
Set to true if linked with Zoho CRM.
primary_contactperson_id
string
Unique Id of primary contact person. This ID will refer to contactperson_id for this customer.
can_add_card
boolean
Set to true if card can be associated.
can_add_bank_account
boolean
Set to true if bank account can be associated.
default_templates
object
Default templates associated with the customer.
invoice_template_id
string
Unique Id used to denote the invoice template.
creditnote_template_id
string
Unique Id used to denote the credit note template.
documents
array
List of files attached to a particular customer.
can_show_in_portal
Set to true if the attachment can be viewed in Client Portal.
file_name
Name of the attached file.
file_type
Type of the attached file.
file_size
file_size_formatted
document_id
Unique ID of the attached file.
attachment_order
Order of the attached file for a particular customer.
{
"customer_id": "903000000000099",
"display_name": "Bowman Furniture",
"salutation": "Mr.",
"first_name": "Benjamin",
"last_name": "George",
"email": "benjamin.george@bowmanfurniture.com",
"tags": [
{
"tag_option_id": "460000000054280",
"is_tag_mandatory": false,
"tag_name": "Colors",
"tag_id": "460000000054182",
"tag_option_name": "Black"
}
],
"company_name": "Bowman Furniture",
"phone": 23467278,
"mobile": 938237475,
"website": "www.bowmanfurniture.com",
"is_portal_enabled": true,
"department": "Marketing",
"designation": "Evangelist",
"billing_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"shipping_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"currency_code": "USD",
"currency_id": "90300000000097",
"ach_supported": true,
"twitter": "BowmanFurniture",
"facebook": "BowmanFurniture",
"skype": "Bowman Furniture",
"notes": "Bowman Furniture",
"gst_no": "33AAAAA0000A1Z5",
"gst_treatment": "business_gst",
"tax_reg_no": 12345678912345,
"tds_tax_id": 982000000557012,
"tax_treatment": "string",
"tax_regime": "general_legal_person",
"is_tds_registered": true,
"place_of_contact": "TN",
"price_precision": 2,
"unused_credits": 0,
"outstanding": 0,
"status": "active",
"custom_fields": [
{
"index": 1,
"value": 129890,
"data_type": "text",
"label": "label"
}
],
"zcrm_account_id": "903000800069001",
"zcrm_contact_id": "903000000098214",
"updated_time": "2016-06-05T02:30:08-0700",
"created_time": "2016-06-05T12:30:08-0700",
"source": "user",
"payment_terms": 0,
"payment_terms_label": "Due on receipt",
"is_linked_with_zohocrm": false,
"primary_contactperson_id": "903000001045003",
"can_add_card": true,
"can_add_bank_account": true,
"default_templates": {
"invoice_template_id": "90300000311340",
"creditnote_template_id": "90300000232140"
},
"documents": [
{
"can_show_in_portal": true,
"file_name": "Rental Agreement.pdf",
"file_type": "pdf",
"file_size": 5447,
"file_size_formatted": "5.3 KB",
"document_id": "903000005689",
"attachment_order": 1
}
]
}
Create a customer
A new customer can a be created separately as well as at the time of creation of a new subscription.
OAuth Scope : ZohoSubscriptions.customers.CREATE
Arguments
display_name
string
(Required)
Name of the customer which will be displayed in the interface and invoices.
salutation
string
Salutation of the customer.
first_name
string
First name of the customer.
last_name
string
Last name of the customer.
email
string
(Required)
Email address of the customer.
tags
array
tag_id
long
ID of the Tag
tag_option_id
long
Id of the Tag Option
company_name
string
Registered name of the company the customer represents.
phone
string
Customer's landline or fixed-line number.
mobile
string
Customer's mobile phone number.
department
string
Customer's department.
designation
string
Customer's designation.
website
string
Customer's website if any.
billing_address
object
Customer's billing address object. It contains
attention,street, city, state,zip,country, state_code and fax. attention
string
Attention of the customer's billing address.
street
string
Street of the customer's billing address.
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.
state_code
string
State Code of the Customer's billing address. Find their region's code here
fax
string
Fax number for the customer's billing address.
shipping_address
object
Customer's shipping address object. It contains
attention,street, city, state,zip,country, state_code and fax. attention
string
Attention of the customer's shipping address.
street
string
Name of the street of the customer's shipping address.
city
string
Name of the city of the customer's shipping address.
state
string
Name of the state of the customer's shipping address.
zip
string
Zip code of the customer's shipping address.
country
string
Country name of the customer's shipping address.
state_code
string
State Code of the customer's shipping address. Find their region's code here
fax
string
Fax number of the customer's shipping address.
payment_terms
integer
Net payment term for the customer.
payment_terms_label
string
Text field of payment terms.
currency_code
string
, default is currency_code chosen in organization profile settings
Currency code of the currency in which the customer wants to pay. If currency_code is not specified here, the currency chosen in your Zoho Billing organization will be used for billing.
ach_supported
boolean
, default is false
Set to true if ACH payment is supported for the customer.
twitter
string
Twitter profile of the customer.
facebook
string
Facebook profile of the customer.
skype
string
Skype ID of the customer
notes
string
A short note about the customer.
is_portal_enabled
boolean
Is Client portal enabled for the customer.
gst_no
string
India GST
only
GSTIN Number for the customer.
gst_treatment
string
India GST
only
GST Treatment for the customer.
Allowed values for
Allowed values for
gst_treatment : business_gst, business_none, consumer, overseasbusiness_gst - For a GST Registered business owner. business_none - For a GST unregistered business owner. consumer - For a consumer. overseas - Customer for whom you export your goods/services. place_of_contact
string
India GST
only
Customer's place of contact.
vat_treatment
string
VAT
only
VAT treatment of the contact.Allowed Values:
uk (A business that is located in the UK.),eu_vat_registered (A business that is reg for VAT and trade goods between Northern Ireland and EU. This node is available only for organizations enabled for NI protocal in VAT Settings.) andoverseas (A business that is located outside UK. Pre Brexit, this was split as eu_vat_registered, eu_vat_not_registered and non_eu ). tax_reg_no
string
🇲🇽
Mexico
only
12 digit Tax Registration number of a contact with Tax treatment as
home_country_mexico, border_region_mexico, non_mexico. Consumers generic RFC: XAXX010101000, Overseas generic RFC: XEXX010101000 tds_tax_id
string
🇲🇽
Mexico
only
ID of the TDS tax.
tax_treatment
string
🇲🇽
Mexico
only
VAT treatment of the contact.Allowed Values:
home_country_mexico (A business that is located within MX)border_region_mexico (A business that is located in the northern and southern border regions in MX)non_mexico (A business that is located outside MX). tax_regime
string
🇲🇽
Mexico
only
Tax Regime of the contact.Allowed Values:
general_legal_person, legal_entities_non_profit, resident_abroad, production_cooperative_societies, agricultural_livestock, optional_group_of_companies, coordinated, simplified_trust, wages_salaries_income, lease, property_disposal_acquisition, other_income, resident_abroad, divident_income, individual_business_professional, interest_income, income_obtaining_price, no_tax_obligation, tax_incorporation, income_through_technology_platform, simplified_trust. is_tds_registered
boolean
🇲🇽
Mexico
only
Boolean to check if tax is registered.
vat_reg_no
string
VAT
only
VAT Registration number of a contact with length should be between 2 and 12 characters.
is_taxable
string
Sales Tax
,
GST
only
Set to true if customer's transactions must be tax inclusive.
tax_id
string
Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if
is_taxable is true. tax_authority_id
string
(Required) for applying Tax exemption to a customer.
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_authority_name
string
(Required) for applying Tax exemption to a customer.
Sales Tax
only
Unique name of the tax authority. Either tax_authority_id or tax_authority_name can be given.
tax_exemption_id
string
Sales Tax
,
GST
only
Unique ID of the tax exemption.
tax_exemption_code
string
Sales Tax
,
GST
only
Unique code of the tax exemption.
default_templates
object
Default templates associated with the customer.
invoice_template_id
string
Unique Id used to denote the invoice template.
creditnote_template_id
string
Unique Id used to denote the credit note template.
custom_fields
array
Additional fields for customers.
label
string
Label of the custom field.
value
string
Value of the custom field.
Headers
X-com-zoho-subscriptions-organizationid
string
(Required)
ID of the organization
parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/customers"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/customers")
.post(body)
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'POST',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
'content-type': 'application/json'
},
body: '{"field1":"value1","field2":"value2"}'
};
fetch('https://www.zohoapis.com/billing/v1/customers', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
'content-type': "application/json"
}
conn.request("POST", "/billing/v1/customers", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "POST",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/customers",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
"content-type": "application/json"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();
curl --request POST \
--url https://www.zohoapis.com/billing/v1/customers \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695' \
--header 'content-type: application/json' \
--data '{"field1":"value1","field2":"value2"}'
{
"display_name": "Bowman Furniture",
"salutation": "Mr.",
"first_name": "Benjamin",
"last_name": "George",
"email": "benjamin.george@bowmanfurniture.com",
"tags": [
{
"tag_id": "460000000054182",
"tag_option_id": "460000000054280"
}
],
"company_name": "Bowman Furniture",
"phone": 23467278,
"mobile": 938237475,
"department": "Marketing",
"designation": "Evangelist",
"website": "www.bowmanfurniture.com",
"billing_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"shipping_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"payment_terms": 0,
"payment_terms_label": "Due on receipt",
"currency_code": "USD",
"ach_supported": true,
"twitter": "BowmanFurniture",
"facebook": "BowmanFurniture",
"skype": "Bowman Furniture",
"notes": "Bowman Furniture",
"is_portal_enabled": true,
"gst_no": "33AAAAA0000A1Z5",
"gst_treatment": "business_gst",
"place_of_contact": "TN",
"vat_treatment": "overseas",
"tax_reg_no": 12345678912345,
"tds_tax_id": 982000000557012,
"tax_treatment": "string",
"tax_regime": "general_legal_person",
"is_tds_registered": true,
"vat_reg_no": 51423456782,
"is_taxable": true,
"tax_id": "903000002345",
"tax_authority_id": "903000006345",
"tax_authority_name": "ATO",
"tax_exemption_id": "903000006345",
"tax_exemption_code": "GST FREE",
"default_templates": {
"invoice_template_id": "90300000311340",
"creditnote_template_id": "90300000232140"
},
"custom_fields": [
{
"label": "label",
"value": 129890
}
]
}
{
"code": 0,
"message": "The customer has been created",
"customer": {
"customer_id": "903000000000099",
"display_name": "Bowman Furniture",
"salutation": "Mr.",
"first_name": "Benjamin",
"last_name": "George",
"email": "benjamin.george@bowmanfurniture.com",
"tags": [
{
"tag_option_id": "460000000054280",
"is_tag_mandatory": false,
"tag_name": "Colors",
"tag_id": "460000000054182",
"tag_option_name": "Black"
}
],
"company_name": "Bowman Furniture",
"phone": 23467278,
"mobile": 938237475,
"website": "www.bowmanfurniture.com",
"is_portal_enabled": true,
"department": "Marketing",
"designation": "Evangelist",
"billing_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"shipping_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"currency_code": "USD",
"currency_id": "90300000000097",
"ach_supported": true,
"twitter": "BowmanFurniture",
"facebook": "BowmanFurniture",
"skype": "Bowman Furniture",
"notes": "Bowman Furniture",
"gst_no": "33AAAAA0000A1Z5",
"gst_treatment": "business_gst",
"tax_reg_no": 12345678912345,
"tds_tax_id": 982000000557012,
"tax_treatment": "string",
"tax_regime": "general_legal_person",
"is_tds_registered": true,
"place_of_contact": "TN",
"price_precision": 2,
"unused_credits": 0,
"outstanding": 0,
"status": "active",
"custom_fields": [
{
"index": 1,
"value": 129890,
"data_type": "text",
"label": "label"
}
],
"zcrm_account_id": "903000800069001",
"zcrm_contact_id": "903000000098214",
"updated_time": "2016-06-05T02:30:08-0700",
"created_time": "2016-06-05T12:30:08-0700",
"source": "user",
"payment_terms": 0,
"payment_terms_label": "Due on receipt",
"is_linked_with_zohocrm": false,
"primary_contactperson_id": "903000001045003",
"can_add_card": true,
"can_add_bank_account": true,
"default_templates": {
"invoice_template_id": "90300000311340",
"creditnote_template_id": "90300000232140"
},
"documents": [
{
"can_show_in_portal": true,
"file_name": "Rental Agreement.pdf",
"file_type": "pdf",
"file_size": 5447,
"file_size_formatted": "5.3 KB",
"document_id": "903000005689",
"attachment_order": 1
}
]
}
}
List all customers
List of all customers. You can list customers based on various filter criterias. The allowed values for filter_by are Status.(All, Active, Inactive, Gapps, Crm, NonSubscribers, PortalEnabled, PortalDisabled).
OAuth Scope : ZohoSubscriptions.customers.READ
Query Parameters
page
integer
Page number to be fetched. Default value is 1.
per_page
integer
Number of records to be fetched per page. Default value is 200.
Headers
X-com-zoho-subscriptions-organizationid
string
(Required)
ID of the organization
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/customers"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/customers")
.get()
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'GET',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
}
};
fetch('https://www.zohoapis.com/billing/v1/customers', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
conn.request("GET", "/billing/v1/customers", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "GET",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/customers",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl --request GET \
--url https://www.zohoapis.com/billing/v1/customers \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695'
{
"code": 0,
"message": "success",
"customers": [
{
"customer_id": "903000000000099",
"display_name": "Bowman Furniture",
"salutation": "Mr.",
"first_name": "Benjamin",
"last_name": "George",
"email": "benjamin.george@bowmanfurniture.com",
"tags": [
{
"tag_id": "460000000054182",
"tag_option_id": "460000000054280"
}
],
"company_name": "Bowman Furniture",
"phone": 23467278,
"mobile": 938237475,
"website": "www.bowmanfurniture.com",
"department": "Marketing",
"designation": "Evangelist",
"currency_code": "USD",
"unused_credits": 0,
"outstanding": 0,
"is_gapps_customer": false,
"updated_time": "2016-06-05T02:30:08-0700",
"created_time": "2016-06-05T12:30:08-0700",
"has_attachment": true
},
{...},
{...}
]
}
Update a customer
Update details of an existing customer.
OAuth Scope : ZohoSubscriptions.customers.UPDATE
Arguments
display_name
string
(Required)
Name of the customer which will be displayed in the interface and invoices.
salutation
string
Salutation of the customer.
first_name
string
First name of the customer.
last_name
string
Last name of the customer.
email
string
(Required)
Email address of the customer.
tags
array
tag_id
long
ID of the Tag
tag_option_id
long
Id of the Tag Option
company_name
string
Registered name of the company the customer represents.
phone
string
Customer's landline or fixed-line number.
mobile
string
Customer's mobile phone number.
billing_address
object
Customer's billing address object. It contains
attention,street, city, state,zip,country, state_code and fax. attention
string
Attention of the customer's billing address.
street
string
Street of the customer's billing address.
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.
state_code
string
State Code of the Customer's billing address. Find their region's code here
fax
string
Fax number for the customer's billing address.
shipping_address
object
Customer's shipping address object. It contains
attention,street, city, state,zip,country, state_code and fax. attention
string
Attention of the customer's shipping address.
street
string
Name of the street of the customer's shipping address.
city
string
Name of the city of the customer's shipping address.
state
string
Name of the state of the customer's shipping address.
zip
string
Zip code of the customer's shipping address.
country
string
Country name of the customer's shipping address.
state_code
string
State Code of the customer's shipping address. Find their region's code here
fax
string
Fax number of the customer's shipping address.
fax
string
Fax number for the customer's billing address.
currency_code
string
, default is currency_code chosen in organization profile settings
Currency code of the currency in which the customer wants to pay. If currency_code is not specified here, the currency chosen in your Zoho Billing organization will be used for billing.
twitter
string
Twitter profile of the customer.
facebook
string
Facebook profile of the customer.
skype
string
Skype ID of the customer
is_portal_enabled
boolean
Is Client portal enabled for the customer.
gst_no
string
India GST
only
GSTIN Number for the customer.
gst_treatment
string
India GST
only
GST Treatment for the customer.
Allowed values for
Allowed values for
gst_treatment : business_gst, business_none, consumer, overseasbusiness_gst - For a GST Registered business owner. business_none - For a GST unregistered business owner. consumer - For a consumer. overseas - Customer for whom you export your goods/services. place_of_contact
string
India GST
only
Customer's place of contact.
vat_treatment
string
VAT
only
VAT treatment of the contact.Allowed Values:
uk (A business that is located in the UK.),eu_vat_registered (A business that is reg for VAT and trade goods between Northern Ireland and EU. This node is available only for organizations enabled for NI protocal in VAT Settings.) andoverseas (A business that is located outside UK. Pre Brexit, this was split as eu_vat_registered, eu_vat_not_registered and non_eu ). vat_reg_no
string
VAT
only
VAT Registration number of a contact with length should be between 2 and 12 characters.
is_taxable
string
Sales Tax
,
GST
only
Set to true if customer's transactions must be tax inclusive.
tax_id
string
Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if
is_taxable is true. tax_authority_id
string
(Required) for applying Tax exemption to a customer.
Sales Tax
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_authority_name
string
(Required) for applying Tax exemption to a customer.
Sales Tax
only
Unique name of the tax authority. Either tax_authority_id or tax_authority_name can be given.
tax_exemption_id
string
Sales Tax
,
GST
only
Unique ID of the tax exemption.
tax_exemption_code
string
Sales Tax
,
GST
only
Unique code of the tax exemption.
default_templates
object
Default templates associated with the customer.
invoice_template_id
string
Unique Id used to denote the invoice template.
creditnote_template_id
string
Unique Id used to denote the credit note template.
tax_reg_no
string
🇲🇽
Mexico
only
12 digit Tax Registration number of a contact with Tax treatment as
home_country_mexico, border_region_mexico, non_mexico. Consumers generic RFC: XAXX010101000, Overseas generic RFC: XEXX010101000 tds_tax_id
string
🇲🇽
Mexico
only
ID of the TDS tax.
tax_treatment
string
🇲🇽
Mexico
only
VAT treatment of the contact.Allowed Values:
home_country_mexico (A business that is located within MX)border_region_mexico (A business that is located in the northern and southern border regions in MX)non_mexico (A business that is located outside MX). tax_regime
string
🇲🇽
Mexico
only
Tax Regime of the contact.Allowed Values:
general_legal_person, legal_entities_non_profit, resident_abroad, production_cooperative_societies, agricultural_livestock, optional_group_of_companies, coordinated, simplified_trust, wages_salaries_income, lease, property_disposal_acquisition, other_income, resident_abroad, divident_income, individual_business_professional, interest_income, income_obtaining_price, no_tax_obligation, tax_incorporation, income_through_technology_platform, simplified_trust. is_tds_registered
boolean
🇲🇽
Mexico
only
Boolean to check if tax is registered.
custom_fields
array
Additional fields for customers.
index
integer
Index of the custom field. It can hold any value from 1 to 10.
value
string
Value of the custom field.
label
string
Label of the custom field.
data_type
string
Data type of the custom field.
Path Parameters
customer_id
string
(Required)
Unique identifier of the customer.
Headers
X-com-zoho-subscriptions-organizationid
string
(Required)
ID of the organization
parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/customers/903000000000099"
type: PUT
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/customers/903000000000099")
.put(body)
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'PUT',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
'content-type': 'application/json'
},
body: '{"field1":"value1","field2":"value2"}'
};
fetch('https://www.zohoapis.com/billing/v1/customers/903000000000099', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
'content-type': "application/json"
}
conn.request("PUT", "/billing/v1/customers/903000000000099", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "PUT",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/customers/903000000000099",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
"content-type": "application/json"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();
curl --request PUT \
--url https://www.zohoapis.com/billing/v1/customers/903000000000099 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695' \
--header 'content-type: application/json' \
--data '{"field1":"value1","field2":"value2"}'
{
"display_name": "Bowman Furniture",
"salutation": "Mr.",
"first_name": "Benjamin",
"last_name": "George",
"email": "benjamin.george@bowmanfurniture.com",
"tags": [
{
"tag_id": "460000000054182",
"tag_option_id": "460000000054280"
}
],
"company_name": "Bowman Furniture",
"phone": 23467278,
"mobile": 938237475,
"billing_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"shipping_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"fax": 4527389,
"currency_code": "USD",
"twitter": "BowmanFurniture",
"facebook": "BowmanFurniture",
"skype": "Bowman Furniture",
"is_portal_enabled": true,
"gst_no": "33AAAAA0000A1Z5",
"gst_treatment": "business_gst",
"place_of_contact": "TN",
"vat_treatment": "overseas",
"vat_reg_no": 51423456782,
"is_taxable": true,
"tax_id": "903000002345",
"tax_authority_id": "903000006345",
"tax_authority_name": "ATO",
"tax_exemption_id": "903000006345",
"tax_exemption_code": "GST FREE",
"default_templates": {
"invoice_template_id": "90300000311340",
"creditnote_template_id": "90300000232140"
},
"tax_reg_no": 12345678912345,
"tds_tax_id": 982000000557012,
"tax_treatment": "string",
"tax_regime": "general_legal_person",
"is_tds_registered": true,
"custom_fields": [
{
"index": 1,
"value": 129890,
"label": "label",
"data_type": "text"
}
]
}
{
"code": 0,
"message": "The customer details have been updated.",
"customer": {
"customer_id": "903000000000099",
"display_name": "Bowman Furniture",
"salutation": "Mr.",
"first_name": "Benjamin",
"last_name": "George",
"email": "benjamin.george@bowmanfurniture.com",
"tags": [
{
"tag_option_id": "460000000054280",
"is_tag_mandatory": false,
"tag_name": "Colors",
"tag_id": "460000000054182",
"tag_option_name": "Black"
}
],
"company_name": "Bowman Furniture",
"phone": 23467278,
"mobile": 938237475,
"website": "www.bowmanfurniture.com",
"department": "Marketing",
"designation": "Evangelist",
"is_portal_enabled": true,
"billing_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"shipping_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"currency_code": "USD",
"currency_id": "90300000000097",
"ach_supported": true,
"price_precision": 2,
"unused_credits": 0,
"outstanding": 0,
"notes": "Bowman Furniture",
"status": "active",
"custom_fields": [
{
"index": 1,
"value": 129890,
"label": "label",
"data_type": "text"
}
],
"zcrm_account_id": "903000800069001",
"zcrm_contact_id": "903000000098214",
"updated_time": "2016-06-05T02:30:08-0700",
"created_time": "2016-06-05T12:30:08-0700",
"source": "user",
"payment_terms_label": "Due on receipt",
"is_linked_with_zohocrm": false,
"primary_contactperson_id": "903000001045003",
"can_add_card": true,
"can_add_bank_account": true,
"default_templates": [
{
"invoice_template_id": "90300000311340",
"creditnote_template_id": "90300000232140"
}
],
"documents": [
{
"can_show_in_portal": true,
"file_name": "Rental Agreement.pdf",
"file_type": "pdf",
"file_size": 5447,
"file_size_formatted": "5.3 KB",
"document_id": "903000005689",
"attachment_order": 1
}
]
}
}
Retrieve a customer
Details of an existing customer.
OAuth Scope : ZohoSubscriptions.customers.READ
Path Parameters
customer_id
string
(Required)
Unique identifier of the customer.
Headers
X-com-zoho-subscriptions-organizationid
string
(Required)
ID of the organization
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/customers/903000000000099"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/customers/903000000000099")
.get()
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'GET',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
}
};
fetch('https://www.zohoapis.com/billing/v1/customers/903000000000099', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
conn.request("GET", "/billing/v1/customers/903000000000099", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "GET",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/customers/903000000000099",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl --request GET \
--url https://www.zohoapis.com/billing/v1/customers/903000000000099 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695'
{
"code": 0,
"message": "success",
"customer": {
"customer_id": "903000000000099",
"display_name": "Bowman Furniture",
"salutation": "Mr.",
"first_name": "Benjamin",
"last_name": "George",
"email": "benjamin.george@bowmanfurniture.com",
"tags": [
{
"tag_option_id": "460000000054280",
"is_tag_mandatory": false,
"tag_name": "Colors",
"tag_id": "460000000054182",
"tag_option_name": "Black"
}
],
"company_name": "Bowman Furniture",
"phone": 23467278,
"mobile": 938237475,
"website": "www.bowmanfurniture.com",
"designation": "Evangelist",
"department": "Marketing",
"is_portal_enabled": true,
"billing_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"shipping_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"currency_code": "USD",
"currency_id": "90300000000097",
"ach_supported": true,
"gst_no": "33AAAAA0000A1Z5",
"gst_treatment": "business_gst",
"tax_reg_no": 12345678912345,
"tds_tax_id": 982000000557012,
"tax_treatment": "string",
"tax_regime": "general_legal_person",
"is_tds_registered": true,
"place_of_contact": "TN",
"price_precision": 2,
"unused_credits": 0,
"outstanding": 0,
"notes": "Bowman Furniture",
"status": "active",
"custom_fields": [
{
"index": 1,
"value": 129890,
"data_type": "text",
"label": "label"
}
],
"zcrm_account_id": "903000800069001",
"zcrm_contact_id": "903000000098214",
"updated_time": "2016-06-05T02:30:08-0700",
"created_time": "2016-06-05T12:30:08-0700",
"source": "user",
"payment_terms_label": "Due on receipt",
"is_linked_with_zohocrm": false,
"primary_contactperson_id": "903000001045003",
"can_add_card": true,
"can_add_bank_account": true,
"default_templates": {
"invoice_template_id": "90300000311340",
"creditnote_template_id": "90300000232140"
},
"documents": [
{
"can_show_in_portal": true,
"file_name": "Rental Agreement.pdf",
"file_type": "pdf",
"file_size": 5447,
"file_size_formatted": "5.3 KB",
"document_id": "903000005689",
"attachment_order": 1
}
]
}
}
Delete a customer
Delete an existing customer.
OAuth Scope : ZohoSubscriptions.customers.DELETE
Path Parameters
customer_id
string
(Required)
Unique identifier of the customer.
Headers
X-com-zoho-subscriptions-organizationid
string
(Required)
ID of the organization
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/customers/903000000000099"
type: DELETE
headers: headers_data
connection: <connection_name>
];
info response;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/customers/903000000000099")
.delete(null)
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'DELETE',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
}
};
fetch('https://www.zohoapis.com/billing/v1/customers/903000000000099', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
conn.request("DELETE", "/billing/v1/customers/903000000000099", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "DELETE",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/customers/903000000000099",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl --request DELETE \
--url https://www.zohoapis.com/billing/v1/customers/903000000000099 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695'
{
"code": 0,
"message": "The customer has been deleted."
}
Retrieve a customer Using CRM Reference
Details of an existing customer using CRM Reference ID. reference_id can be CRM Contact ID (for Contacts only sync) or CRM Account ID (For accounts only and Accounts and its contacts sync). Query param value of reference_id_type must be given accoridngly.
OAuth Scope : ZohoSubscriptions.customers.READ
Path Parameters
reference_id
string
(Required)
Unique identifier of the customer reference.
Query Parameters
reference_id_type
string
Possible values are
zcrm_account_id and zcrm_contact_id.Headers
X-com-zoho-subscriptions-organizationid
string
(Required)
ID of the organization
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/customers/reference/903000000021976"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/customers/reference/903000000021976")
.get()
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'GET',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
}
};
fetch('https://www.zohoapis.com/billing/v1/customers/reference/903000000021976', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
conn.request("GET", "/billing/v1/customers/reference/903000000021976", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "GET",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/customers/reference/903000000021976",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl --request GET \
--url https://www.zohoapis.com/billing/v1/customers/reference/903000000021976 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695'
{
"code": 0,
"message": "success",
"customer": {
"customer_id": "903000000000099",
"display_name": "Bowman Furniture",
"salutation": "Mr.",
"first_name": "Benjamin",
"last_name": "George",
"email": "benjamin.george@bowmanfurniture.com",
"company_name": "Bowman Furniture",
"phone": 23467278,
"mobile": 938237475,
"website": "www.bowmanfurniture.com",
"designation": "Evangelist",
"department": "Marketing",
"is_portal_enabled": true,
"billing_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"shipping_address": {
"attention": "Benjamin George",
"street": "Harrington Bay Street",
"city": "Salt Lake City",
"state": "CA",
"zip": 92612,
"country": "U.S.A",
"state_code": "CA",
"fax": 4527389
},
"currency_code": "USD",
"currency_id": "90300000000097",
"ach_supported": true,
"gst_no": "33AAAAA0000A1Z5",
"gst_treatment": "business_gst",
"tax_reg_no": 12345678912345,
"tds_tax_id": 982000000557012,
"tax_treatment": "string",
"tax_regime": "general_legal_person",
"is_tds_registered": true,
"place_of_contact": "TN",
"price_precision": 2,
"unused_credits": 0,
"outstanding": 0,
"notes": "Bowman Furniture",
"status": "active",
"custom_fields": [
{
"index": 1,
"value": 129890,
"data_type": "text",
"label": "label"
}
],
"zcrm_account_id": "903000800069001",
"zcrm_contact_id": "903000000098214",
"updated_time": "2016-06-05T02:30:08-0700",
"created_time": "2016-06-05T12:30:08-0700",
"source": "user",
"payment_terms_label": "Due on receipt",
"is_linked_with_zohocrm": false,
"primary_contactperson_id": "903000001045003",
"can_add_card": true,
"can_add_bank_account": true,
"default_templates": {
"invoice_template_id": "90300000311340",
"creditnote_template_id": "90300000232140"
},
"documents": [
{
"can_show_in_portal": true,
"file_name": "Rental Agreement.pdf",
"file_type": "pdf",
"file_size": 5447,
"file_size_formatted": "5.3 KB",
"document_id": "903000005689",
"attachment_order": 1
}
]
}
}
List of transactions
List of all transactions associated with a particular customer.
OAuth Scope : ZohoSubscriptions.customers.READ
Query Parameters
filter_by
string
Transactions of particular type can be filtered by passing a param
filter_by. The allowed values for filter_by are TransactionType.(All, INVOICE, PAYMENT, CREDIT, REFUND) customer_id
string
To list Transactions of a particular customer use the parameter
customer_id. page
integer
Page number to be fetched. Default value is 1.
per_page
integer
Number of records to be fetched per page. Default value is 200.
Headers
X-com-zoho-subscriptions-organizationid
string
(Required)
ID of the organization
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/transactions"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/transactions")
.get()
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'GET',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
}
};
fetch('https://www.zohoapis.com/billing/v1/transactions', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
conn.request("GET", "/billing/v1/transactions", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "GET",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/transactions",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl --request GET \
--url https://www.zohoapis.com/billing/v1/transactions \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695'
{
"code": 0,
"message": "success",
"transactions": [
{
"transaction_id": "903000000094534",
"reference_id": "903000000021976",
"date": "2016-09-30",
"type": "invoice",
"status": "active",
"amount": "20.50"
},
{...},
{...}
]
}
Mark as active
Change status of the customer to active.
OAuth Scope : ZohoSubscriptions.customers.CREATE
Path Parameters
customer_id
string
(Required)
Unique identifier of the customer.
Headers
X-com-zoho-subscriptions-organizationid
string
(Required)
ID of the organization
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/customers/903000000000099/markasactive"
type: POST
headers: headers_data
connection: <connection_name>
];
info response;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/customers/903000000000099/markasactive")
.post(null)
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'POST',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
}
};
fetch('https://www.zohoapis.com/billing/v1/customers/903000000000099/markasactive', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
conn.request("POST", "/billing/v1/customers/903000000000099/markasactive", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "POST",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/customers/903000000000099/markasactive",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl --request POST \
--url https://www.zohoapis.com/billing/v1/customers/903000000000099/markasactive \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695'
{
"code": 0,
"message": "The customer has been marked as active."
}
Mark as inactive
Change status of the customer to inactive. A cutomer can be marked as inactive only if there is no active subscription associated with the customer.
OAuth Scope : ZohoSubscriptions.customers.CREATE
Path Parameters
customer_id
string
(Required)
Unique identifier of the customer.
Headers
X-com-zoho-subscriptions-organizationid
string
(Required)
ID of the organization
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/customers/903000000000099/markasinactive"
type: POST
headers: headers_data
connection: <connection_name>
];
info response;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/customers/903000000000099/markasinactive")
.post(null)
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'POST',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
}
};
fetch('https://www.zohoapis.com/billing/v1/customers/903000000000099/markasinactive', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
conn.request("POST", "/billing/v1/customers/903000000000099/markasinactive", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "POST",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/customers/903000000000099/markasinactive",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl --request POST \
--url https://www.zohoapis.com/billing/v1/customers/903000000000099/markasinactive \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695'
{
"code": 0,
"message": "The customer has been marked as inactive."
}