API Docs
/
No Results Found
Customers

Customers

A customer object allows you to keep track of all customer related information.

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
Show Sub-Attributes arrow
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.
Show Sub-Attributes arrow
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.
Show Sub-Attributes arrow
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 Subscriptions 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 gst_treatment :
business_gst, business_none, consumer, overseas
business_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.
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.
Show Sub-Attributes arrow
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.
Show Sub-Attributes arrow
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.
Show Sub-Attributes arrow
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.

Example

{ "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", "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": 5, "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.
oauthscope : 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
Show Sub-Attributes arrow
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.
Show Sub-Attributes arrow
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.
Show Sub-Attributes arrow
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 Subscriptions 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 gst_treatment :
business_gst, business_none, consumer, overseas
business_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.) and
overseas (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
(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.
Show Sub-Attributes arrow
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.
Show Sub-Attributes arrow
label
string
Label of the custom field.
value
string
Value of the custom field.

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/customers -X POST -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "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": 5, "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", "vat_reg_no": 51423456782, "is_taxable": true, "tax_id": "903000002345", "tax_authority_id": null, "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 } ] }

Response Example

{ "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", "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": 5, "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).
oauthscope : ZohoSubscriptions.customers.READ

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/customers -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "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.
oauthscope : 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
Show Sub-Attributes arrow
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.
Show Sub-Attributes arrow
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.
Show Sub-Attributes arrow
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 Subscriptions 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 gst_treatment :
business_gst, business_none, consumer, overseas
business_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.) and
overseas (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.
Show Sub-Attributes arrow
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.

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id} -X PUT -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "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" } }

Response Example

{ "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.
oauthscope : ZohoSubscriptions.customers.READ

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id} -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "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", "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.
oauthscope : ZohoSubscriptions.customers.DELETE

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id} -X DELETE -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "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.
oauthscope : ZohoSubscriptions.customers.READ

Query Parameters

reference_id_type
Possible values are zcrm_account_id and zcrm_contact_id.

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/customers/reference/{reference_id} -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "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", "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.
oauthscope : ZohoSubscriptions.customers.READ

Query Parameters

filter_by
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
To list Transactions of a particular customer use the parameter customer_id.

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/transactions -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "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.
oauthscope : ZohoSubscriptions.customers.CREATE

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/markasactive -X POST -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "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.
oauthscope : ZohoSubscriptions.customers.CREATE

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/markasinactive -X POST -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "The customer has been marked as inactive." }