Introduction

The Partner API allows you as a partner to perform all the GET operations that you do in your partner store.

Partner API is built using REST principles. This ensures predictable URLs that make it easy to write and retrieve data related to your partner store. This API follows HTTP rules.

Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint. The API Root Endpoint is

https://store.zoho.com/api/v1/partner

Getting Started

To use our API, you must satisfy these prerequisites.

A valid Zoho username and password.

An Authentication Token (oauthtoken).

Generate OAuth

Partner APIs use the OAuth 2.0 protocol to authorize and authenticate calls. To generate a OAuth token, you need to first create a client ID and Client Secret using the Self Client by accessing the following URL

https://api-console.zoho.com/

After generating the Client ID and Client Secret, you should generate the OAuth code with the required scope to obtain the access token and the refresh_token. You should generate OAuth token for the following scopes :

ZohoPayments.transactions.READ, ZohoPayments.subscriptions.READ,ZohoPayments.leads.READ

You can mention multiple scopes

Next, you need to get the Refresh and access token using code:


Method : POST

https://accounts.zoho.com/oauth/v2/token?code=1000.dd7e47321d48b8a7e312e3d6eb1a9bb8.b6c07ac766ec11da98bf6a261e24dca4&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf&grant_type=authorization_code

To get Access token using refresh token

Methods : POST

https://accounts.zoho.com/oauth/v2/token?refresh_token=1000.8ecd474019e31d52d2f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf&grant_type=refresh_token

The token generated will be valid for one hour.

Multiple Data Centres

The Partner store is hosted on multiple data centres. You have to use the correct domain from which you need to retrieve the data.

Data CenterDomainBase API URI
United States.comhttps://store.zoho.com/
Europe.euhttps://store.zoho.eu/
India.inhttps://store.zoho.in/
Australia.com.auhttps://store.zoho.com.au/

HTTP Methods

Partner API uses appropriate HTTP verbs for every action. However, currently we only support GET actions. We will soon provide the POST and PUT actions in our upcoming releases.

Response

All responses will be in the JSON format.

Error

Pagination

Partner APIs helps you to retrieve lists of subscriptions, transactions, leads and other resources Each API request will return 200 items by default. The pagination information will be included in the header API response under the node name has_more.

By default first page will be listed. For navigating through pages, use the page parameter.The per_page parameter can be used to set the number of records that you want to receive in response.

API Call Limit

API calls are limited to provide better service and availability to all the users. The following are the limitations when you make an API request.

Calls per minute : Only 100 API requests per minute are allowed.

Transaction Start Date: You can retrieve transactions only from 2019-01-01. Transactions that happened before this date cannot be retrieved using the API call.

Subscriptions API

Get the list of all the subscriptions in your partner store with pagination.

GET /subscriptions

scope : ZohoPayments.subscriptions.READ, ZohoPayments.fullaccess.READ

The following are the attributes and values that you can provide to get the subscription list.

AttributeValue
next_recurring_date_fromThe recurring date from which you want the subscription list (yyyy-mm-dd).
next_recurring_date_toThe recurring date till which you want the subscription list (yyyy-mm-dd).
billing_frequencymonthly, quarterly, half_yearly or yearly.
pricing_typepartner_price or list_price.
subscription_start_date_fromsubscription date from which you want the subscription list (yyyy-mm-dd).
subscription_start_date_tosubscription date till which you want the subscription list (yyyy-mm-dd).
email_idCustomer's email address.
service_idsubscription service

Sample Response

The Unique ID for the Subscription API is subscription_id.

The following are the attributes and values that you will in the response.

AttributePossible Values
subscription_typeonline, offline.
pricing_typelist_price, partner_price.

Active Subscriptions

List all the active subscriptions with the pagination.

GET /subscriptions/status/active

Inactive Subscriptions

List all the inactive subscriptions with the pagination

GET /subscriptions/status/inactive

Specific Subscription

List the details of a specific subscription

GET /subscriptions/{subscription_id}

Example request : /subscriptions/14000000293023

Sample Response :

 

 

Transactions of a subscription

List all the transactions of a specific subscription

GET /subscriptions/{subscription_id}/transactions

The following are the attributes and values that you can provide to get the transaction list of a subscription.

AttributeValue
transaction_date_fromThe date from which the transactions should be listed.
transaction_date_toThe date till which the transactions should be listed.
billing_frequencymonthly, quarterly, half_yearly or yearly
pricing_typepartner_price or list_price

Sample response for a list of transactions for a specific subscription.

The Unique ID for the Transaction API is transaction_id.

The following are the attributes and values that you will in the response.

AttributePossible Values
subscription_typeonline, offline.
transaction_typesignup,reactivate,cancel,upgrade,downgrade,recurring_failure,recurring,card_change,refund,
data_sync,one_time_payment,offline_to_online,past_due,skip_month,scheduled_cancel,
subscription_resumed,one_time_charge.
pricing_typelist_price, partner_price

Invoiced Transactions  of a subscription

List all the invoiced transactions of a subscription with the pagination.

GET /subscriptions/{subscription_id}/transactions/status/invoiced

The following are the attributes and values that you can use to list the invoiced transactions of a subscription.

AttributeValue
transaction_date_fromThe date from which the transaction should be listed.
transaction_date_toThe date till which the transaction should be listed.
billing_frequencymonthly, quarterly, half_yearly or yearly
pricing_typepartner_price or list_price
service_idtransaction service

Sample response for a invoiced transaction

Transactions API:

List all the transactions with the pagination.

scope : ZohoPayments.transactions.READ,ZohoPayments.fullaccess.READ

GET /transactions

The following are the attributes and values that you can use to list all the transactions.

AttributeValue
transaction_date_fromThe date from which the transaction should be listed.
transaction_date_toThe date till which the transaction should be listed.
billing_frequencymonthly, quarterly, half_yearly or yearly.
pricing_typepartner_price or list_price.
service_idtransaction service

 

Invoiced Transactions

List all the invoiced transactions

GET /transactions/status/invoiced

Specific Transaction

List the details of a specific transaction.

GET /transactions/{transaction_id}

 

Invoiced Transaction

List the details of a transaction with the invoiced entity, invoice amount and invoice number (if invoiced).

GET /transactions/{:transaction_id}/status/invoiced

 

Invoice Attachment

List the invoice attachment for a transaction.

GET /transactions/{:transaction_id}/invoice/attachment

The API call is limited to 10 requests/minute.

 

Leads API

List all the leads that have tagged in your partner store with the pagination.

scope : ZohoPayments.leads.READ,ZohoPayments.fullaccess.READ

GET /leads

The following are the attributes and values that you can use to list all the leads.

AttributeValue
registration_date_fromThe date from which the leads registered should be listed.
registration_date_toThe date till which the leads registered should be listed.
email_idCustomer email address
service_idlead service

Sample response

The Unique ID for the Leads API is lead_id.

Details of a specific lead

List the details of a specific lead.

GET /leads/{lead_id}

Sample Request to get list of transactions using access_token

$ curl https://store.zoho.com/api/v1/partner/transactions

      -H  'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'

Commission API

 Get the list of commissions with pagination

scope : ZohoPayments.commissions.READ,ZohoPayments.fullaccess.READ

GET /commissions

The following are the attributes and values that you can use to list all the commissions.

AttributeValue
datecommission accounted date (yyyy-mm-dd).
subscription.email_idcustomer's email address
transaction.service_namesubscription service name
transaction.transaction_datecustomer transaction date.
entitycommission billing entity (Zoho US, Zoho Singapore, Zoho Netherlands, Zoho Germany, Zoho Mexico, Zoho Australia, Zoho Canada, Zoho India, Zoho Nigeria)

The pagination details will be part of the response. 

Sample response

Commission Sample response