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 Center | Domain | Base API URI |
|---|---|---|
| United States | .com | https://store.zoho.com/ |
| Europe | .eu | https://store.zoho.eu/ |
| India | .in | https://store.zoho.in/ |
| Australia | .com.au | https://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.
| Attribute | Value |
|---|---|
| next_recurring_date_from | The recurring date from which you want the subscription list (yyyy-mm-dd). |
| next_recurring_date_to | The recurring date till which you want the subscription list (yyyy-mm-dd). |
| billing_frequency | monthly, quarterly, half_yearly or yearly. |
| pricing_type | partner_price or list_price. |
| subscription_start_date_from | subscription date from which you want the subscription list (yyyy-mm-dd). |
| subscription_start_date_to | subscription date till which you want the subscription list (yyyy-mm-dd). |
| email_id | Customer's email address. |
| service_id | subscription 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.
| Attribute | Possible Values |
|---|---|
| subscription_type | online, offline. |
| pricing_type | list_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.
| Attribute | Value |
|---|---|
| transaction_date_from | The date from which the transactions should be listed. |
| transaction_date_to | The date till which the transactions should be listed. |
| billing_frequency | monthly, quarterly, half_yearly or yearly |
| pricing_type | partner_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.
| Attribute | Possible Values |
|---|---|
| subscription_type | online, offline. |
| transaction_type | signup,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_type | list_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.
| Attribute | Value |
|---|---|
| transaction_date_from | The date from which the transaction should be listed. |
| transaction_date_to | The date till which the transaction should be listed. |
| billing_frequency | monthly, quarterly, half_yearly or yearly |
| pricing_type | partner_price or list_price |
| service_id | transaction 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.
| Attribute | Value |
|---|---|
| transaction_date_from | The date from which the transaction should be listed. |
| transaction_date_to | The date till which the transaction should be listed. |
| billing_frequency | monthly, quarterly, half_yearly or yearly. |
| pricing_type | partner_price or list_price. |
| service_id | transaction 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.
| Attribute | Value |
|---|---|
| registration_date_from | The date from which the leads registered should be listed. |
| registration_date_to | The date till which the leads registered should be listed. |
| email_id | Customer email address |
| service_id | lead 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.
| Attribute | Value |
|---|---|
| date | commission accounted date (yyyy-mm-dd). |
| subscription.email_id | customer's email address |
| transaction.service_name | subscription service name |
| transaction.transaction_date | customer transaction date. |
| entity | commission 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
